Skip to main content
O endpoint POST /api/v1/send-template envia um template HSM (mensagem estruturada pré-aprovada pela Meta) via WhatsApp Oficial. É o único método válido para iniciar contato com números que não interagiram nas últimas 24 horas. Se o contato ou a conversa ainda não existirem no Tivar, ambos são criados automaticamente. Canal suportado: whatsapp-official (Meta Cloud API) exclusivamente.

​
Requisição

POST /api/v1/send-template

​
Headers

HeaderValor
AuthorizationBearer <workspace_api_key> (obrigatório)
Content-Typeapplication/json

​
Parâmetros do body

​
phone
string
required
Número do destinatário. Aceita formato E.164 (+5511999998888) ou somente dígitos com DDD (5511999998888). Mínimo de 10 dígitos.
​
channel
string
required
Deve ser "whatsapp-official". Templates HSM não são suportados por outros canais.
​
templateName
string
required
Nome exato do template aprovado no Meta Business Manager. O valor é case-sensitive.
​
language
string
default:"pt_BR"
Código do idioma do template, conforme registrado no Meta Business Manager. Padrão: "pt_BR".
​
variables
string[]
Lista de valores para substituir as variáveis {{1}}, {{2}}, {{3}} etc. do template, na ordem em que aparecem. Cada item pode ser string ou número. Passe um array vazio [] se o template não tiver variáveis.
​
integrationId
string
UUID de uma integração específica do workspace. Se omitido, o Tivar usa a integração conectada mais recentemente.
​
agentId
string
UUID de um agente de IA. Quando informado, a conversa é atribuída automaticamente a esse agente.
​
contactName
string
Nome de exibição do contato. Usado apenas no momento da criação — se o contato já existir, esse campo é ignorado.
As variáveis do array variables substituem os placeholders {{1}}, {{2}}, {{3}} etc. na ordem em que aparecem. O número de itens no array deve corresponder exatamente ao número de variáveis definidas no template aprovado.

​
Resposta de sucesso

200 OK
​
success
boolean
required
true quando o template foi enviado com sucesso.
​
conversationId
string
required
UUID da conversa no Tivar.
​
contactId
string
required
UUID do contato no Tivar.
​
messageId
string
required
UUID da mensagem no banco de dados do Tivar.
​
waMessageId
string
required
ID da mensagem retornado pela Meta.
​
contactCreated
boolean
required
true se o contato foi criado nesta requisição.
​
conversationCreated
boolean
required
true se a conversa foi criada nesta requisição.
​
template
object
required
Dados do template enviado.
​
sent_at
string
required
Timestamp ISO 8601 do envio da mensagem.

​
Erros possíveis

Statuserror / meta_error_codeO que fazer
400"Parâmetros obrigatórios: phone, templateName, channel"Verifique se os três campos obrigatórios estão presentes.
400"Templates HSM só são suportados pelo canal \"whatsapp-official\""O campo channel deve ser "whatsapp-official".
400"variables deve ser array"Passe um array, mesmo que vazio: [].
401"API Key inválida"Verifique a API Key.
404"Nenhuma integração WhatsApp Oficial conectada"Conecte a integração no painel do Tivar.
429"Muitas requisições. Limite: 60/min por workspace."Aguarde alguns segundos e reenvie.
4xx + meta_error_code: 132001Template não encontrado ou não aprovadoConfirme o templateName e o idioma no Meta Business Manager.
4xx + meta_error_code: 132000Número de variáveis incorretoO array variables deve ter exatamente o mesmo número de {{N}} definidos no template.

​
Exemplos

curl -X POST https://<seu-dominio>/api/v1/send-template \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999998888",
    "channel": "whatsapp-official",
    "templateName": "confirmacao_pedido",
    "language": "pt_BR",
    "variables": ["João", "Pedido #1234", "R$ 150,00"]
  }'