Skip to main content
O endpoint POST /api/v1/send-message envia uma mensagem de texto para um número de telefone via WhatsApp Oficial (Meta Cloud API) ou UAZAPI. Se o contato ou a conversa ainda não existirem no Tivar, ambos são criados automaticamente. É o endpoint ideal para disparos ativos quando o número está dentro da janela de 24 horas do WhatsApp. Canais suportados: whatsapp-official (Meta Cloud API) e uazapi.

​
Requisição

POST /api/v1/send-message

​
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.
​
message
string
required
Texto a ser enviado. Entre 1 e 4096 caracteres.
​
channel
string
required
Canal de envio. Use "whatsapp-official" para a API oficial da Meta ou "uazapi" para WhatsApp via UAZAPI.
​
integrationId
string
UUID de uma integração específica do workspace. Se omitido, o Tivar usa a integração conectada mais recentemente para o canal escolhido.
​
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.

​
Resposta de sucesso

200 OK
​
success
boolean
required
true quando a mensagem foi enviada 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 Tivar.
​
waMessageId
string
required
ID da mensagem retornado pelo provedor (WhatsApp Oficial ou UAZAPI).
​
contactCreated
boolean
required
true se o contato foi criado nesta requisição.
​
conversationCreated
boolean
required
true se a conversa foi criada nesta requisição.
​
sent_at
string
required
Timestamp ISO 8601 do envio da mensagem.

​
Erros possíveis

StatuserrorO que fazer
400"Parâmetros obrigatórios: phone, message, channel"Verifique se os três campos obrigatórios estão presentes.
400"channel inválido. Use \"whatsapp-official\" ou \"uazapi\""Corrija o valor de channel.
400"phone inválido. Forneça em E.164 ou só dígitos (mínimo 10)."Formate o número corretamente.
400"message deve ser string de 1–4096 caracteres"Verifique se a mensagem não está vazia nem excede 4096 caracteres.
400"Integração não está conectada"Reconecte a integração no painel do Tivar.
401"API Key inválida"Verifique a API Key.
403"Workspace inativo"Workspace suspenso — entre em contato com o suporte.
404"Nenhuma integração \"whatsapp-official\" conectada neste workspace"Conecte uma integração do canal informado.
429"Muitas requisições. Limite: 60/min por workspace."Aguarde alguns segundos e reenvie.
4xx + "requires_template": trueJanela de 24h encerrada (código Meta 131047)Use /api/v1/send-template com um template HSM aprovado.
O WhatsApp Oficial só permite enviar mensagens de texto livre dentro de uma janela de 24 horas após a última interação do contato. Se a resposta incluir "requires_template": true, o número está fora dessa janela. Nesse caso, use POST /api/v1/send-template com um template HSM aprovado pela Meta.

​
Exemplos

curl -X POST https://<seu-dominio>/api/v1/send-message \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999998888",
    "message": "Olá! Seu pedido foi confirmado.",
    "channel": "whatsapp-official"
  }'