Enviar Mensagem - Brainchat

Envie mensagens programaticamente via WhatsApp.

POST https://wapi.stegia.com.br/functions/v1/send-message

Para gerenciar contatos (criar, atualizar, etiquetar) ou gerenciar conversas (atribuir, mudar status, adicionar notas) sem enviar mensagem, prefira os endpoints dedicados:

📇 API de Contatos — criar, atualizar, gerenciar tags
💬 API de Conversas — atribuir operador, mudar status, notas internas

Os parâmetros assignTo e portfolio neste endpoint continuam funcionando para retrocompatibilidade.

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
`instanceId`	string	✅*	ID do canal no Brainchat ou chave de embed (`emb_...`). *Informe este ou `connectedPhone`
`connectedPhone`	string	✅*	Alternativa a `instanceId`: número conectado do canal
`phone`	string	✅	Número do destinatário (formato: `5511999999999`)
`messageType`	string	Depende	Tipo: `text` (padrão), `image`, `video`, `audio`, `document`, `option_list`, `location`, `contact` ou `multi_contact`
`message`	string	Depende	Texto da mensagem ou legenda da mídia
`mediaUrl`	string	Depende	URL pública HTTPS do arquivo de mídia
`mediaFilename`	string	❌	Nome do arquivo para documentos (ex: `relatorio.pdf`)
`optionList`	object	Depende	Objeto com título, botão e opções — obrigatório para `messageType: "option_list"`
`location`	object	Depende	Para `messageType: "location"`: `latitude` (−90 a 90) e `longitude` (−180 a 180) obrigatórios; `name` e `address` opcionais
`contact`	object	Depende	Para `messageType: "contact"`: `displayName` e `phones` (lista) obrigatórios
`contacts`	array	Depende	Para `messageType: "multi_contact"`: lista de contatos no mesmo formato de `contact`
`cardId`	string	❌	Identificador customizado para rastreamento
`externalRef` / `externalSource`	string	❌	Identificador do atendimento no seu sistema (ex.: id do card) e o nome do sistema. Vincula a conversa a esse identificador (veja Conversas)
`senderDepartment`	string	❌	Departamento mostrado na identificação do operador, quando o canal usa Identificação do operador
`delayMessage`	number	❌	Delay em segundos antes do envio
`delayTyping`	number	❌	Tempo em ms de simulação de digitação antes do envio
`assignTo`	string	❌	E-mail ou UUID do operador para atribuir a conversa
`portfolio`	boolean	❌	Se `true`, adiciona o contato à carteira do operador com prioridade absoluta
`queued`	boolean	❌	Se `true`, a mensagem entra na fila inteligente em vez de envio imediato
`intervalSeconds`	number	❌	Intervalo em segundos entre mensagens na fila (padrão: 30s, min: 10s, max: 3600s)
`sentBy`	string	❌	Origem da mensagem: `ai_agent`, `api`, `scheduled`, `automation`, `operator`, ou qualquer string. Se diferente de `ai_agent`, pausa o agente de IA pelo tempo configurado no agente

Exemplos

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "text",
  "message": "Olá! Como posso ajudar?"
}

Imagem:

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "image",
  "mediaUrl": "https://exemplo.com/imagem.jpg",
  "message": "Legenda opcional"
}

Áudio:

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "audio",
  "mediaUrl": "https://exemplo.com/audio.mp3"
}

Documento:

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "document",
  "mediaUrl": "https://exemplo.com/documento.pdf",
  "message": "Relatório Mensal.pdf",
  "mediaFilename": "Relatório Mensal.pdf"
}

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "option_list",
  "message": "Selecione uma opção:",
  "optionList": {
    "title": "Opções disponíveis",
    "buttonLabel": "Ver opções",
    "options": [
      {
        "id": "1",
        "title": "Suporte Técnico",
        "description": "Problemas técnicos e bugs"
      },
      {
        "id": "2",
        "title": "Vendas",
        "description": "Informações sobre produtos"
      }
    ]
  }
}

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "text",
  "message": "Promoção especial para você!",
  "queued": true,
  "intervalSeconds": 60
}

Com queued: true, a mensagem entra na fila inteligente em vez de ser enviada imediatamente. O sistema calcula automaticamente o próximo horário disponível respeitando o intervalo configurado (intervalSeconds).Comportamento da fila:

Intervalo mínimo: 10 segundos, máximo: 3600 segundos (1 hora), padrão: 30 segundos
Janela de envio padrão: 08:00 às 20:00 (horário do canal)
Mensagens fora do horário são agendadas para o próximo dia útil
Chamadas simultâneas entram na fila sem conflito

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "assignTo": "joao@empresa.com",
  "portfolio": true
}

Quando assignTo está presente mas não há message nem mediaUrl, nenhuma mensagem é enviada ao WhatsApp — apenas a atribuição é feita.

Não é necessário informar messageType
O operador recebe o e-mail de notificação normalmente
Com portfolio: true, o contato é adicionado à carteira do operador
A resposta retorna "mode": "assign_only" confirmando que apenas a atribuição foi realizada

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "text",
  "message": "Olá! Você será atendido pelo João.",
  "assignTo": "joao@empresa.com",
  "portfolio": true
}

O parâmetro assignTo aceita e-mail ou UUID do operador.

Com portfolio: true (opcional), o contato é adicionado à carteira do operador com prioridade absoluta — somente ele verá esse contato.
O operador recebe automaticamente um e-mail de notificação com o nome do contato e um link direto para a conversa no chat.
Se o contato não existir, ele é criado automaticamente com os dados disponíveis.
A reatribuição registra automaticamente uma transferência no histórico e insere uma nota interna na conversa.

{
  "instanceId": "ID_DO_CANAL",
  "phone": "5511999999999",
  "messageType": "text",
  "message": "Mensagem enviada via integração externa.",
  "sentBy": "api"
}

O parâmetro sentBy controla se o agente de IA ativo no canal será pausado após o envio. Não é necessário informar o agentId — o sistema detecta automaticamente o agente vinculado ao canal.A lógica é simples: qualquer valor diferente de ai_agent pausa o agente pelo tempo de Duração da pausa do agente (padrão 30 minutos), quando Pausar quando operador responder está ligado.

sentBy: "ai_agent" → O agente não é pausado (a mensagem é tratada como resposta do próprio agente)
sentBy: "api" → O agente é pausado (integração externa — valor mais comum)
sentBy: "operator" → O agente é pausado (mensagem humana)
sentBy: "automation" → O agente é pausado
sentBy: "scheduled" → O agente é pausado
Sem sentBy → Comportamento padrão, o agente é pausado

A cada nova mensagem com sentBy diferente de ai_agent, o tempo da pausa é renovado.

Todos os parâmetros podem ser combinados livremente em uma única chamada. Por exemplo, é possível enviar uma mensagem com fila inteligente (queued), atribuição (assignTo + portfolio) e controle do agente (sentBy) ao mesmo tempo.

cURL Completo

curl -X POST "https://wapi.stegia.com.br/functions/v1/send-message" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "instanceId": "ID_DO_CANAL",
    "phone": "5511999999999",
    "messageType": "text",
    "message": "Olá! Esta é uma mensagem via API."
  }'

Comportamentos Automáticos

Fila Inteligente (queued)

Quando queued: true, o sistema calcula o próximo horário de envio:

Verifica o último envio para aquele canal
Calcula próximo_envio = MAX(agora, último_envio + intervalo)
Agenda a mensagem com o horário calculado
A fila é processada automaticamente

Limites de velocidade: O intervalo configurável (intervalSeconds) garante que mensagens não sejam enviadas em rajada, evitando banimentos do WhatsApp.Janela de horário: Por padrão, mensagens são enviadas entre 08:00 e 20:00 no fuso do canal. Mensagens agendadas fora desse horário são postergadas.

Pausa do Agente de IA

Se o canal possui um agente de IA ativo, mensagens enviadas via API com sentBy diferente de ai_agent pausam automaticamente o agente para aquele contato, pelo tempo configurado no agente (padrão 30 minutos).Isso evita que o agente responda sobre uma mensagem enviada manualmente por um operador ou automação. A cada nova mensagem humana, o timer de pausa é renovado.Para enviar mensagens via API sem pausar o agente (ex: respostas automáticas do próprio agente), use sentBy: "ai_agent".Qualquer string diferente de ai_agent pausa o agente — os valores api, operator, automation, scheduled são apenas convenções para facilitar a rastreabilidade.

Notificação ao Operador

Quando um contato é atribuído via assignTo, o operador recebe automaticamente um e-mail contendo:

Nome do contato (ou número, se sem nome)
Telefone do contato
Link direto para abrir a conversa no chat (/c/chat/{telefoneCanal}/{telefoneContato})

O e-mail é enviado de forma assíncrona (fire-and-forget) e não bloqueia o envio da mensagem.

Auto-criação de Contato

Se o número informado em phone não existir na base de contatos do canal, o sistema cria automaticamente um novo contato com os dados disponíveis antes de enviar a mensagem.

Informações Importantes

Formato do Telefone

Sempre com código do país: 5511999999999. Use o endpoint Sanitizar Número para normalizar.

Tipos de Mídia

JPG, PNG, MP3, WAV, MP4, PDF — URLs devem ser públicas e HTTPS.

Iniciar Conversa com Agente de IA

Este é um endpoint diferente do send-message. Use-o para acionar o agente de IA proativamente — ele envia a primeira mensagem como se fosse o agente e cria a conversa automaticamente.

POST https://wapi.stegia.com.br/functions/v1/process-ai-agent

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
`instanceId`	string	✅	ID do canal (UUID ou embed_key)
`phone`	string	✅	Número do destinatário (formato: `5511999999999`)
`initiateConversation`	boolean \| string	✅	`true`: envia o `messageText` exatamente como está, em nome do agente. `"agent"`: o agente escreve a primeira mensagem sozinho, usando o `messageText` como instrução e o `externalContext` como dados
`messageText`	string	⚠️	Com `initiateConversation: true`, é o texto enviado ao cliente; com `"agent"`, é a instrução para o agente (o cliente não vê). Obrigatório quando não há `template_id`
`template_id`	string (uuid)	❌	Abre a conversa com um template aprovado em vez de texto livre (única forma em canal Meta fora da janela de 24h). Aceita também `templateId`
`variables`	object	❌	Variáveis do template, no mesmo formato de Enviar Template. Aceita também `templateVariables`
`agentId`	string	❌	UUID do agente (obrigatório se o canal tiver múltiplos agentes)
`contactName`	string	❌	Nome do contato (usado só para nomear/atualizar o cadastro)
`externalContext`	object	❌	Dados externos injetados na conversa — ficam disponíveis como variáveis em `collected_data` para o agente referenciar dinamicamente
`queued`	boolean	❌	Se `true`, a mensagem entra na fila inteligente (apenas texto livre)
`intervalSeconds`	number	❌	Intervalo em segundos entre mensagens na fila
`sentBy`	string	❌	Ignorado neste endpoint — a abertura sempre sai como o agente

Exemplo

{
  "instanceId": "emb_5434740aa6ed1856",
  "phone": "5511999999999",
  "messageText": "Olá! Somos da empresa X e gostaríamos de falar sobre seu cadastro.",
  "agentId": "c365ac34-4704-41cb-adbe-52f72221c79a",
  "initiateConversation": true,
  "queued": true,
  "intervalSeconds": 30,
  "sentBy": "api",
  "externalContext": {
    "nome_cliente": "João Silva",
    "valor_pendente": "R$1.500,00",
    "id_pedido": "12345"
  }
}

Como funciona:

A mensagem é enviada como se fosse o agente (não como operador humano)
A conversa é criada automaticamente no sistema com o agente vinculado
O agente só processa IA quando o contato responder — a primeira mensagem é enviada diretamente
externalContext injeta variáveis externas que são armazenadas em collected_data — o agente pode referenciar essas variáveis durante toda a conversa (ex: nome_cliente, valor_pendente, id_pedido)
Ideal para integrações com CRMs (Pipefy, HubSpot, etc.) onde o agente precisa de contexto externo para conduzir a conversa
Se o contato não existir, ele é criado automaticamente

Abrir a conversa com um template oficial

Em canais Meta Oficial, texto livre só é aceito dentro da janela de 24h. Para iniciar a conversa fora dela, envie template_id — o template aprovado abre a janela e o agente assume assim que o contato responder, já com o externalContext em mãos.

curl -X POST "https://wapi.stegia.com.br/functions/v1/process-ai-agent" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "instanceId": "emb_5434740aa6ed1856",
    "phone": "5511999999999",
    "agentId": "SEU_AGENT_ID",
    "initiateConversation": true,
    "template_id": "00000000-0000-0000-0000-000000000000",
    "variables": { "nome": "João", "pedido": "12345" },
    "externalContext": { "CNPJ": "12345678000199", "cidade": "Campinas" }
  }'

Os valores em variables podem referenciar o contexto externo com {{chave}} — por exemplo "pedido": "{{id_pedido}}" usa o valor enviado em externalContext.

Resposta de sucesso:

{
  "success": true,
  "mode": "proactive_init",
  "via": "template",
  "conversationId": "uuid",
  "messageSent": true,
  "messageId": "wamid.HBgN..."
}

Erros específicos do template (a conversa não é criada nos três primeiros):

Status	`reason`	Quando ocorre
400	`template_not_found`	`template_id` inexistente
400	`template_not_approved`	Template Meta com status diferente de aprovado
400	`template_not_synced_with_meta`	Template Meta sem sincronização
400	`template_from_another_channel`	Template pertence a outro canal
502	`missing_variables` / `template_send_failed`	Falta variável ou o provedor recusou o envio

cURL (texto livre)

curl -X POST "https://wapi.stegia.com.br/functions/v1/process-ai-agent" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "instanceId": "emb_5434740aa6ed1856",
    "phone": "5511999999999",
    "messageText": "Olá! Gostaríamos de falar sobre seu cadastro.",
    "agentId": "SEU_AGENT_ID",
    "initiateConversation": true
  }'

Endpoints Auxiliares

GET — Histórico de Mensagens

Recupere o histórico de mensagens para contexto de IA ou auditoria.

GET https://wapi.stegia.com.br/functions/v1/messages-context

Parâmetros (query string):

Parâmetro	Obrigatório	Descrição
`phone`	✅	Número do telefone
`start`	✅	Data inicial (YYYY-MM-DD)
`end`	✅	Data final (YYYY-MM-DD)
`instanceId`	✅	ID do canal
`limit`	❌	Máximo de mensagens (padrão: 100)
`format`	❌	`conversation` ou `raw`

curl -X GET "https://wapi.stegia.com.br/functions/v1/messages-context?phone=5511999999999&start=2024-01-01&end=2024-12-31&instanceId=ID_DO_CANAL" \
  -H "X-Client-Token: SEU_TOKEN_AQUI"

POST — Sanitizar Número

Endpoint público (sem token) que remove formatação de telefones.

POST https://wapi.stegia.com.br/functions/v1/sanitize-phone-number

curl -X POST "https://wapi.stegia.com.br/functions/v1/sanitize-phone-number" \
  -H "Content-Type: application/json" \
  -d '{"phone": "(11) 99999-9999"}'

Resposta:

{
  "success": true,
  "original": "(11) 99999-9999",
  "sanitized": "11999999999"
}