Modelos de mensagem (templates)

Um modelo é uma mensagem aprovada pela Meta, com texto fixo e variáveis. É o único tipo que a Meta entrega fora da janela de 24 h do cliente (Janela de atendimento de 24 horas); dentro da janela também vale. Modelos são cobrados pela Meta conforme a categoria, dentro ou fora da janela (Cobrança). Use para avisos de pedido, cobrança, lembretes e qualquer primeira mensagem para quem não falou com a empresa nas últimas 24 h.

Onde criar e aprovar#

Você pode criar e gerir modelos pelo app ou pela API (veja "Ler e gerir modelos pela API", abaixo). Nos dois casos, quem aprova é a Meta, e a análise pode levar até 24 horas. O modelo só pode ser enviado com o status APPROVED.

No app do Synergy, a página Modelos (rota /templates): Novo modelo abre o editor (/templates/new) e o envio para análise da Meta sai de lá. Sincronizar com a Meta traz para o app os modelos já criados no WhatsApp Manager.

Para saber quando um modelo foi aprovado ou rejeitado sem abrir o app, assine os campos message_template_status_update e message_template_quality_update no seu webhook (Webhooks).

Como enviar#

Mesmo endpoint de Enviar mensagens, com type: "template":

template.name é o nome do modelo aprovado e template.language.code o idioma como foi aprovado (por exemplo pt_BR). Um modelo sem variáveis nem botões com valor não precisa de components.
components traz os valores das variáveis: um item header, um body e um button por botão que tenha valor. Botões sem valor (telefone, URL fixa) não entram.
Num modelo com variáveis numeradas ({{1}}, {{2}}), os parâmetros vão na ordem. Num modelo com variáveis nomeadas ({{first_name}}), cada parâmetro leva parameter_name.

Sem variáveis:

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "boas_vindas",
    "language": {
      "code": "pt_BR",
      "policy": "deterministic"
    }
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "boas_vindas",
      "language": {
        "code": "pt_BR",
        "policy": "deterministic"
      }
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "boas_vindas",
            "language": {
                "code": "pt_BR",
                "policy": "deterministic",
            },
        },
    },
)
print(res.status_code, res.json())

Corpo: texto, valor e data#

Os parâmetros do body podem ser text, currency (amount_1000 é o valor vezes 1000: R$ 100,99 = 100990; code é a moeda ISO 4217) e date_time (fallback_value é o texto que aparece).

Com variáveis nomeadas:

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "pedido_confirmado",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Maria"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "R$ 100,99",
              "code": "BRL",
              "amount_1000": 100990
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "10 de janeiro de 2026"
            }
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "pedido_confirmado",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Maria"
            },
            {
              "type": "currency",
              "currency": {
                "fallback_value": "R$ 100,99",
                "code": "BRL",
                "amount_1000": 100990
              }
            },
            {
              "type": "date_time",
              "date_time": {
                "fallback_value": "10 de janeiro de 2026"
              }
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "pedido_confirmado",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "Maria",
                        },
                        {
                            "type": "currency",
                            "currency": {
                                "fallback_value": "R$ 100,99",
                                "code": "BRL",
                                "amount_1000": 100990,
                            },
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "10 de janeiro de 2026",
                            },
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "pedido_saiu",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "parameter_name": "first_name",
            "text": "Maria"
          },
          {
            "type": "text",
            "parameter_name": "order_number",
            "text": "42"
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "pedido_saiu",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "parameter_name": "first_name",
              "text": "Maria"
            },
            {
              "type": "text",
              "parameter_name": "order_number",
              "text": "42"
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "pedido_saiu",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "parameter_name": "first_name",
                            "text": "Maria",
                        },
                        {
                            "type": "text",
                            "parameter_name": "order_number",
                            "text": "42",
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Cabeçalho com variável de texto#

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "promocao_sazonal",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "Black Friday"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "30 de novembro"
          },
          {
            "type": "text",
            "text": "BF25"
          },
          {
            "type": "text",
            "text": "25%"
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "promocao_sazonal",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "text",
              "text": "Black Friday"
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "30 de novembro"
            },
            {
              "type": "text",
              "text": "BF25"
            },
            {
              "type": "text",
              "text": "25%"
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "promocao_sazonal",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "Black Friday",
                        },
                    ],
                },
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "30 de novembro",
                        },
                        {
                            "type": "text",
                            "text": "BF25",
                        },
                        {
                            "type": "text",
                            "text": "25%",
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Cabeçalho com mídia#

Um modelo com cabeçalho de imagem, vídeo ou documento exige a mídia em todo envio, em header.parameters (um parâmetro só). Use id (de um upload, Mídia) ou link, nunca os dois. Os formatos e tamanhos são os de cada tipo de mensagem. No documento, filename é o nome que o cliente vê.

Imagem:

Documento:

Vídeo e localização seguem a mesma forma: { "type": "video", "video": { "id": "1166846181421424" } } e { "type": "location", "location": { "latitude": "-23.561414", "longitude": "-46.655881", "name": "Loja Paulista", "address": "Av. Paulista, 1000 - São Paulo, SP" } } dentro de header.parameters. O cabeçalho de localização vale para modelos de utilidade ou marketing.

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "pedido_enviado",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://arquivos.example.com/pedidos/42.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Maria"
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "pedido_enviado",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "image",
              "image": {
                "link": "https://arquivos.example.com/pedidos/42.jpg"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Maria"
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "pedido_enviado",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "image",
                            "image": {
                                "link": "https://arquivos.example.com/pedidos/42.jpg",
                            },
                        },
                    ],
                },
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "Maria",
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "boleto_disponivel",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "document",
            "document": {
              "link": "https://arquivos.example.com/boletos/42.pdf",
              "filename": "boleto-pedido-42.pdf"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "10/01/2026"
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "boleto_disponivel",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "document",
              "document": {
                "link": "https://arquivos.example.com/boletos/42.pdf",
                "filename": "boleto-pedido-42.pdf"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "10/01/2026"
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "boleto_disponivel",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "document",
                            "document": {
                                "link": "https://arquivos.example.com/boletos/42.pdf",
                                "filename": "boleto-pedido-42.pdf",
                            },
                        },
                    ],
                },
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "10/01/2026",
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Botões#

Cada botão com valor é um componente button, com sub_type, index (a posição do botão no modelo, a partir de 0; a Meta aceita "0" ou 0) e exatamente um parâmetro.

Resposta rápida (quick_reply). O payload volta no webhook quando o cliente toca, como uma mensagem type: "button" (veja abaixo).

URL dinâmica (url). O modelo tem uma URL com variável no fim (por exemplo https://www.example.com/pedidos/{{1}}); o text completa esse fim. Codifique caracteres especiais (%20, %C3%A7…). Um botão de URL fixa não entra em components.

Copiar código (copy_code). O coupon_code é o que o botão copia, com até 20 caracteres.

Flow (flow). O botão abre um WhatsApp Flow. flow_token identifica a sessão (padrão da Meta: unused); flow_action_data são os dados de entrada da primeira tela. Num Flow com endpoint da Synergy, o token vem de POST /v1/numbers/{phone_number_id}/flows/{flow_id}/token e é obrigatório (sem ele, 400 código 1390009). Enviar um modelo com botão de Flow exige a feature waFlows (403, código 1390007). Veja WhatsApp Flows.

A resposta do formulário chega como nfm_reply, igual ao Flow enviado como mensagem interativa (Mensagens interativas).

Catálogo (catalog). O produto da miniatura:

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "confirmar_entrega",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "42"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "CONFIRM_42"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "RESCHEDULE_42"
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "confirmar_entrega",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "42"
            }
          ]
        },
        {
          "type": "button",
          "sub_type": "quick_reply",
          "index": "0",
          "parameters": [
            {
              "type": "payload",
              "payload": "CONFIRM_42"
            }
          ]
        },
        {
          "type": "button",
          "sub_type": "quick_reply",
          "index": "1",
          "parameters": [
            {
              "type": "payload",
              "payload": "RESCHEDULE_42"
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "confirmar_entrega",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "42",
                        },
                    ],
                },
                {
                    "type": "button",
                    "sub_type": "quick_reply",
                    "index": "0",
                    "parameters": [
                        {
                            "type": "payload",
                            "payload": "CONFIRM_42",
                        },
                    ],
                },
                {
                    "type": "button",
                    "sub_type": "quick_reply",
                    "index": "1",
                    "parameters": [
                        {
                            "type": "payload",
                            "payload": "RESCHEDULE_42",
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "rastrear_pedido",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "42"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "pedido-42"
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "rastrear_pedido",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "42"
            }
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": "0",
          "parameters": [
            {
              "type": "text",
              "text": "pedido-42"
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "rastrear_pedido",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "42",
                        },
                    ],
                },
                {
                    "type": "button",
                    "sub_type": "url",
                    "index": "0",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "pedido-42",
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "cupom_desconto",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "25%"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": "0",
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "BF25"
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "cupom_desconto",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "25%"
            }
          ]
        },
        {
          "type": "button",
          "sub_type": "copy_code",
          "index": "0",
          "parameters": [
            {
              "type": "coupon_code",
              "coupon_code": "BF25"
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "cupom_desconto",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "25%",
                        },
                    ],
                },
                {
                    "type": "button",
                    "sub_type": "copy_code",
                    "index": "0",
                    "parameters": [
                        {
                            "type": "coupon_code",
                            "coupon_code": "BF25",
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "cadastro_rapido",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "flow",
        "index": "0",
        "parameters": [
          {
            "type": "action",
            "action": {
              "flow_token": "cadastro-pedido-42",
              "flow_action_data": {
                "order_id": "42"
              }
            }
          }
        ]
      }
    ]
  }
}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "cadastro_rapido",
      "language": {
        "code": "pt_BR"
      },
      "components": [
        {
          "type": "button",
          "sub_type": "flow",
          "index": "0",
          "parameters": [
            {
              "type": "action",
              "action": {
                "flow_token": "cadastro-pedido-42",
                "flow_action_data": {
                  "order_id": "42"
                }
              }
            }
          ]
        }
      ]
    }
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "5511999999999",
        "type": "template",
        "template": {
            "name": "cadastro_rapido",
            "language": {
                "code": "pt_BR",
            },
            "components": [
                {
                    "type": "button",
                    "sub_type": "flow",
                    "index": "0",
                    "parameters": [
                        {
                            "type": "action",
                            "action": {
                                "flow_token": "cadastro-pedido-42",
                                "flow_action_data": {
                                    "order_id": "42",
                                },
                            },
                        },
                    ],
                },
            ],
        },
    },
)
print(res.status_code, res.json())

JSON

{ "type": "button", "sub_type": "catalog", "index": 0, "parameters": [{ "type": "action", "action": { "thumbnail_product_retailer_id": "tenis-azul-42" } }] }

A resposta do cliente a um botão de modelo#

O toque num botão de resposta rápida de um modelo chega no webhook messages como type: "button", não como interactive. button.payload é o payload que você deu no envio (ou o texto do botão, se não deu) e context.id é o wamid do modelo:

JSON

{
  "from": "5511999999999",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMzEyAA==",
  "timestamp": "1767225600",
  "type": "button",
  "context": {
    "from": "554430000000",
    "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA=="
  },
  "button": {
    "payload": "CONFIRM_42",
    "text": "Confirmar"
  }
}

Ler e gerir modelos pela API#

Os modelos são da conta do WhatsApp Business de cada número. Por isso as rotas levam o phone_number_id: GET /v1/numbers lista os números da chave.

Operação	Chamada	Escopo da chave
Listar	`GET /v1/numbers/{phone_number_id}/templates`	`messages`
Consultar um	`GET /v1/numbers/{phone_number_id}/templates/{template_id}`	`messages`
Criar	`POST /v1/numbers/{phone_number_id}/templates`	`management`
Editar	`POST /v1/numbers/{phone_number_id}/templates/{template_id}`	`management`
Apagar	`DELETE /v1/numbers/{phone_number_id}/templates/{template_id}`	`management`
Subir a mídia de exemplo	`POST /v1/numbers/{phone_number_id}/templates/media`	`management`

Todas exigem a feature api no plano. Os erros vêm no formato da Graph API (Erros). Uma chave de assistente do MCP nunca recebe management, então uma IA lê e envia modelos, mas não os cria nem apaga.

Listar#

Filtros opcionais: status (padrão APPROVED), name (por prefixo, sem curinga), language (idioma exato, como pt_BR) e limit (até 100).

A lista vem do cache da Synergy: a leitura nunca espera a Meta. Com o cache vencido, ela responde o que tem, com syncing: true, e atualiza em seguida; só a primeira leitura de uma conta busca na Meta antes de responder. Repetir a mesma consulta em até 30 segundos devolve a mesma lista. A leitura é limitada a 120 chamadas por minuto por chave, somando todos os números (Limites de taxa). O id de um modelo de outra conta responde 404 (código 100).

Criar#

O corpo é o da Meta e vai para ela, que devolve a resposta. O modelo nasce PENDING; o aprovado ou rejeitado chega no evento message_template_status_update.

O corpo pode ter até 64 KB. Um nome repetido, um texto recusado e os demais erros da Meta voltam como ela os mandou.

Cabeçalho com mídia: suba o exemplo antes#

A Meta exige uma mídia de exemplo para aprovar um cabeçalho de imagem, vídeo ou documento. Suba o arquivo e use o handle na criação:

Até 5 MB, multipart/form-data com o campo file, e Content-Length obrigatório. Tipos aceitos: image/jpeg, image/png, video/mp4 e application/pdf. No modelo, o componente HEADER leva "example": { "header_handle": ["4::aW1hZ2UvanBlZw==:ARb3x9Qa"] }.

Editar e apagar#

As duas respondem { "success": true }. Os limites de edição (quantas vezes, e em que status) são os da Meta. A escrita é limitada a 30 chamadas por minuto por chave.

No SDK: wa.templates.list(), get, create, update, delete e uploadMedia. No n8n: o recurso Template.

Exemplo

curl

curl 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates?status=APPROVED&name=pedido' \
  -H "Authorization: Bearer $SYNERGY_API_KEY"

JavaScript

const res = await fetch(
  'https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates?status=APPROVED&name=pedido',
  { headers: { Authorization: `Bearer ${process.env.SYNERGY_API_KEY}` } },
);
const { data } = await res.json();

Python

res = requests.get(
    "https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates",
    params={"status": "APPROVED", "name": "pedido"},
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
)
data = res.json()["data"]

JSON

{
  "data": [{
    "id": "594425479261596",
    "name": "pedido_enviado",
    "language": "pt_BR",
    "status": "APPROVED",
    "category": "UTILITY",
    "parameter_format": "POSITIONAL",
    "components": [{ "type": "BODY", "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.", "example": { "body_text": [["Maria", "#42"]] } }]
  }]
}

Exemplo

curl -X POST 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "pedido_enviado",
    "language": "pt_BR",
    "category": "UTILITY",
    "parameter_format": "POSITIONAL",
    "components": [
      { "type": "BODY", "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.", "example": { "body_text": [["Maria", "#42"]] } }
    ]
  }'

JSON

{ "id": "594425479261596", "status": "PENDING", "category": "UTILITY" }

Exemplo

curl -X POST 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates/media' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -F 'file=@exemplo.jpg;type=image/jpeg'

JSON

{ "handle": "4::aW1hZ2UvanBlZw==:ARb3x9Qa" }

Exemplo

# editar: os componentes (e, se quiser, a categoria); a Meta revisa de novo
curl -X POST 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates/594425479261596' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"components":[{"type":"BODY","text":"Olá {{1}}, seu pedido {{2}} está a caminho.","example":{"body_text":[["Maria","#42"]]}}]}'

# apagar
curl -X DELETE 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates/594425479261596' \
  -H "Authorization: Bearer $SYNERGY_API_KEY"

Erros comuns#

Sintoma	Causa	O que fazer
Erro da Meta logo no envio (400 com o corpo dela)	`name` ou `language.code` que não batem com um modelo aprovado; ou parâmetros que não batem com as variáveis e botões do modelo	Confira nome, idioma e a quantidade e o tipo dos parâmetros no modelo, na página Modelos do app
O modelo está em análise, rejeitado ou pausado	Só `APPROVED` é entregue	Veja o status em Modelos e assine `message_template_status_update`
Cabeçalho de mídia recusado	Falta o parâmetro de mídia no `header`, ou o arquivo não está nos formatos e tamanhos aceitos	Veja Mídia
Botão de URL recusado	O valor tem caracteres especiais sem codificação, ou `index` aponta para um botão sem variável	Codifique o valor; o `index` conta a partir de 0
`copy_code` recusado	Código com mais de 20 caracteres	Use até 20 caracteres
400 código 1390009	Modelo com botão de Flow de endpoint da Synergy, sem `flow_token` válido	Emita o token (WhatsApp Flows)
403 código 1390007	O plano não inclui WhatsApp Flows	Mude o plano
Envio aceito (200), depois `failed` no webhook com código 131049	A Meta limita quantos modelos de marketing um cliente recebe num período; também limita reenvios repetidos	Espere ao menos 24 h antes de reenviar ao mesmo cliente
Envio aceito (200), depois `failed` no webhook	A Meta recusou na entrega; o motivo vem em `statuses[].errors`	Leia `errors[].code` e `error_data.details` (Receber mensagens e status)
429 código 1390006	O volume do ciclo do plano esgotou: os envios automatizados param	Recarga, mudança de plano ou próximo ciclo (Erros)

Quando a Meta recusa, o erro dela volta com o status e o corpo que ela mandou; os códigos da Synergy (faixa 139xxxx) estão em Erros.

Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.