Criar um modelo
POST/v1/numbers/{phone_number_id}/templates
Cria um modelo na conta do WhatsApp Business deste número. O corpo é o da Meta e vai para ela; a resposta da Meta volta. O modelo nasce PENDING até a Meta revisar; a mudança de status chega no evento message_template_status_update.
Corpo de até 64 KB. Mídia de exemplo de um cabeçalho: suba antes por POST /v1/numbers/{phone_number_id}/templates/media e use o handle.
Requer#
- Escopo da chave
- Gerenciar webhooks
managementComo os escopos funcionam - Recurso do plano
- API e webhooks
apiVer os planos que incluem - Formato
- Próprio do Synergy. Erros em
{ "error": "…" }.
Parâmetros#
No caminho#
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| phone_number_id | string | obrigatório | O phone_number_id do número na Meta (o mesmo da Cloud API). Precisa ser um número ativo da organização da chave. |
Cabeçalhos#
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | obrigatório | Sua chave de API, no formato Bearer <chave>. Veja Autenticação. |
Corpo#
Tipo de conteúdo: application/json.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | obrigatório | Minúsculas, dígitos e _. |
| language | string | obrigatório | Por exemplo pt_BR. |
| category | string | obrigatório | Valores: MARKETING, UTILITY, AUTHENTICATION. |
| components | object[] | obrigatório | |
| parameter_format | string | opcional | Valores: POSITIONAL, NAMED. |
Respostas#
| Status | Código | Quando acontece |
|---|---|---|
| 200 | — | Modelo em revisão |
| 400 | 100 | Corpo acima de 64 KB |
| 400 | 100 | O corpo não é um objeto JSON |
| 401 | 190 | Sem Authorization: Bearer, chave malformada ou forjada, chave revogada, ou chave sem acesso a este número |
| 403 | 200 | A chave não tem o escopo management |
| 403 | 1390004 | O plano da organização não inclui a API |
| 404 | 100 | O phone_number_id não é um número ativo desta organização (ou não tem de 5 a 20 dígitos) |
| 429 | 130429 | Mais de 2000 requisições em 10 s com esta chave neste número (Retry-After: 10) |
| 429 | 130429 | O número acabou de recusar por vazão, ou está sobrecarregado: o 429 se repete por 200 ms (Retry-After: 1) |
| 429 | 130429 | Mais de 30 escritas de modelos em 60 s com esta chave (Retry-After: 60) |
| 503 | 2 | Serviço temporariamente indisponível |
| Outros | 131047 | Erro da Meta, como ela mandou |
Os erros no formato da Meta trazem o código em error.code. Ver todos os erros.
Corpo da resposta 200#
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | obrigatório | |
| status | string | obrigatório | |
| category | string | obrigatório |
Limites de taxa#
- Borda: 2000 requisições a cada 10 s por chave × número (API_EDGE_LIMIT).
- Escrita de modelos: 30 requisições a cada 60 s por chave (API_MGMT_LIMIT, o mesmo balde da gestão de webhooks).
Notas#
- Número:
{phone_number_id}precisa ser um número de WhatsApp ativo que a chave alcança; qualquer outro (inclusive o id de uma conta do Instagram) responde 404 (código 100), sem acordar o número. - Erros no formato da Graph API, inclusive os da Meta repassados (por exemplo nome repetido).
Requisição
curl
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"]]}}]}'JavaScript
const res = await fetch('https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"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"
]
]
}
}
]
}),
});
console.log(res.status, await res.json());Python
import os
import requests
res = requests.post(
"https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates",
headers={
"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
},
json={
"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",
],
],
},
},
],
},
)
print(res.status_code, res.json())Resposta
200
{
"id": "594425479261596",
"status": "PENDING",
"category": "UTILITY"
}400
{
"error": {
"message": "(#100) Invalid parameter.",
"type": "OAuthException",
"code": 100,
"error_data": {
"messaging_product": "whatsapp",
"details": "The body is too large (64 KB max)."
},
"fbtrace_id": "syn-3f9a1c0b"
}
}Há 2 casos com este status; veja a tabela de respostas.
401
{
"error": {
"message": "(#190) Invalid OAuth access token.",
"type": "OAuthException",
"code": 190,
"fbtrace_id": "syn-3f9a1c0b"
}
}403
{
"error": {
"message": "(#200) Permissions error: this key does not have access to this resource.",
"type": "OAuthException",
"code": 200,
"fbtrace_id": "syn-3f9a1c0b"
}
}Há 2 casos com este status; veja a tabela de respostas.
404
{
"error": {
"message": "(#100) Unsupported request: object does not exist or this key cannot reach it.",
"type": "OAuthException",
"code": 100,
"fbtrace_id": "syn-3f9a1c0b"
}
}429
{
"error": {
"message": "(#130429) Rate limit hit: the number's message throughput has been reached.",
"type": "OAuthException",
"code": 130429,
"fbtrace_id": "syn-3f9a1c0b"
}
}Há 3 casos com este status; veja a tabela de respostas.
503
{
"error": {
"message": "(#2) Service temporarily unavailable.",
"type": "OAuthException",
"code": 2,
"fbtrace_id": "syn-3f9a1c0b"
}
}Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.