Listar os modelos do número

GET/v1/numbers/{phone_number_id}/templates

Os modelos de mensagem da conta do WhatsApp Business DESTE número, do cache da Synergy: a leitura nunca espera a Meta (com o cache vencido responde o que tem, com syncing: true, e sincroniza depois). Só a primeira leitura de uma conta busca na Meta antes de responder.

name filtra por PREFIXO (sem curinga: % e _ são letras comuns).

Requer#

Escopo da chave: Enviar mensagens messagesComo os escopos funcionam
Recurso do plano: API e webhooks apiVer os planos que incluem
Formato: Rota do Synergy. Erros no formato da Meta.

Parâmetros#

No caminho#

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.

Na query#

Na query
Nome	Tipo	Obrigatório	Descrição
status	string	opcional	O status na Meta. Padrão `APPROVED`.
name	string	opcional	Prefixo do nome.
language	string	opcional	O idioma exato (por exemplo `pt_BR`).
limit	integer	opcional	Até 100.

Cabeçalhos#

Cabeçalhos
Nome	Tipo	Obrigatório	Descrição
Authorization	string	obrigatório	Sua chave de API, no formato `Bearer <chave>`. Veja Autenticação.

Respostas#

Respostas
Status	Código	Quando acontece
200	—	Um modelo aprovado
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 `messages`
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 120 leituras de modelos em 60 s com esta chave, somando os números (`Retry-After: 60`)
503	2	Serviço temporariamente indisponível

Os erros no formato da Meta trazem o código em error.code. Ver todos os erros.

Corpo da resposta 200#

Campos da resposta 200
Nome	Tipo	Obrigatório	Descrição
data	object[]	obrigatório
data[].id	string	obrigatório
data[].name	string	obrigatório
data[].language	string	obrigatório	Por exemplo `pt_BR`.
data[].status	string	obrigatório	O status na Meta (`APPROVED`, `PENDING`, `REJECTED`, `PAUSED`…).
data[].category	string	obrigatório	`MARKETING`, `UTILITY` ou `AUTHENTICATION`.
data[].parameter_format	string \| null	obrigatório	Valores: `POSITIONAL`, `NAMED`, `null`.
data[].components	object[]	obrigatório	Os componentes como a Meta os descreve.
syncing	boolean	opcional	`true` = a lista veio do cache e uma sincronização com a Meta começou agora; chame de novo em alguns segundos para ver as mudanças.

Limites de taxa#

Borda: 2000 requisições a cada 10 s por chave × número (API_EDGE_LIMIT).
Leitura de modelos: 120 requisições a cada 60 s por chave, somando todos os números dela (API_ORG_LIMIT, balde próprio). Uma resposta 200 fica em cache por 30 s por chave, número e consulta: repetir dentro desse prazo devolve a mesma lista.

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.
Uma chave revogada ainda pode receber, por até 30 s, uma lista que já estava no cache daquela instância do Worker.

Requisição

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', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os

import requests

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

Resposta

200

{
  "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"
              ]
            ]
          }
        }
      ]
    }
  ]
}

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.