Emitir o flow_token de um envio de flow

POST/v1/numbers/{phone_number_id}/flows/{flow_id}/token

Emite o flow_token que o envio de um WhatsApp Flow com endpoint da Synergy precisa. Rota da Synergy, sem equivalente na Meta.

O token é assinado, vale para ESTE número, ESTE flow e ESTE destinatário, e identifica quem pode conversar com o endpoint do flow. Depois de emitir, envie o flow por POST /{version}/{phone_number_id}/messages com o token em interactive.action.parameters.flow_token.

Validade: 3 dias. Corpo de até 4 KB. O destinatário vai no corpo, nunca no caminho.

Requer#

Escopo da chave: Enviar mensagens messagesComo os escopos funcionam
Recurso do plano: API e webhooks api e Formulários no WhatsApp waFlowsVer 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.
flow_id	string	obrigatório	O id do flow na Meta.

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.

Corpo#

Tipo de conteúdo: application/json.

Campos do corpo
Nome	Tipo	Obrigatório	Descrição
to	string	obrigatório	O número de quem vai receber o flow: só dígitos, com DDI.
context	object	opcional	Os dados que o endpoint do flow recebe com o token, validados pelo tipo do flow (até 4 chaves no token). Só valores de texto.

Respostas#

Respostas
Status	Código	Quando acontece
200	—	Token emitido
400	100	Falta `to` (ou o corpo não é JSON)
400	100	`to` não tem de 8 a 20 dígitos
400	100	`context` não é um objeto de textos
400	100	`context` não é o que o tipo do flow espera
400	100	Corpo acima de 4 KB
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
403	1390007	O plano não inclui WhatsApp Flows
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)
404	100	O flow não é deste número (ou o id não tem de 5 a 25 dígitos)
409	1390008	O flow usa o endpoint de outro provedor, ou não pode ser enviado
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`)
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
flow_token	string	obrigatório	Vai em `interactive.action.parameters.flow_token` no envio do flow. Vale para este número, este flow e este destinatário.
expires_at	string	obrigatório	Validade: 3 dias depois da emissão.

Limites de taxa#

Borda: 2000 requisições a cada 10 s por chave × número (API_EDGE_LIMIT).

Notas#

O código responde 409 (código 1390008, "another provider's endpoint") para QUALQUER flow que não pode ser enviado — também um flow só em rascunho ou de um tipo que este número não conhece —, não só para o endpoint de outro provedor.
As chaves aceitas em context dependem do tipo do flow (o schema do tipo valida); este documento não as lista.
Se o destinatário ainda não é um contato do número, ele é criado ao emitir o token.

Requisição

curl

curl -X POST 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/flows/1234567890/token' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to":"5511999999999"}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v1/numbers/106540352242922/flows/1234567890/token', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "5511999999999"
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v1/numbers/106540352242922/flows/1234567890/token",
    headers={
        "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
    },
    json={
        "to": "5511999999999",
    },
)
print(res.status_code, res.json())

Resposta

200

{
  "flow_token": "v1.eyJ2IjoxLCJvIjoib3JnXzEyMyIsInciOiIxMDIyOTAxMjkzNDAzOTgifQ.Zm9vYmFyLXNpZ25hdHVyZS1leGFtcGxl",
  "expires_at": "2026-01-04T00:00:00.000Z"
}

400

{
  "error": {
    "message": "(#100) Invalid parameter.",
    "type": "OAuthException",
    "code": 100,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "The parameter \"to\" is required."
    },
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

Há 5 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á 3 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"
  }
}

Há 2 casos com este status; veja a tabela de respostas.

409

{
  "error": {
    "message": "(#1390008) This flow uses another provider's endpoint and cannot be sent through Synergy.",
    "type": "OAuthException",
    "code": 1390008,
    "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á 2 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.