Primeiros passos

Envie sua primeira mensagem e receba seu primeiro webhook.

Ao fim desta página você terá enviado uma mensagem pela API e recebido o webhook que ela gera. Tudo no sandbox: nada sai para um cliente de verdade, e nenhum dado real é tocado.

O que você precisa

Uma conta Amivu e acesso ao painel. Os comandos abaixo usam curl; se preferir, cada um tem a versão em Node.js, Python e PHP.

Cinco passos

Crie uma chave de sandbox

No painel, vá em Configurações → Desenvolvedores e clique em Criar chave. Escolha o ambiente Sandbox e marque os alcances contacts:write, conversations:write, messages:write e webhooks:write.

O segredo aparece uma única vez. Guarde-o numa variável de ambiente — ele nunca deve entrar em código versionado.

Terminal

export AMIVU_API_KEY="amivu_test_..."

Faça a primeira chamada

Uma leitura, para confirmar que a chave funciona. Num sandbox recém-criado a lista vem vazia — e vazia é a resposta certa.

curl https://api.amivu.com.br/v1/contacts \
  -H "Authorization: Bearer $AMIVU_API_KEY"

Resposta

{
  "object": "list",
  "data": [],
  "pagination": { "has_more": false, "next_cursor": null }
}

Crie um contato e abra uma conversa

O external_id é o identificador da pessoa no seu sistema. Mandá-lo torna esta chamada segura de repetir: se o contato já existir, a Amivu devolve o mesmo, em vez de criar um segundo.

Com o contato em mãos, abra a conversa. O external_id dela é o número do pedido — e é o que impede um reprocessamento de partir o histórico em duas telas.

curl https://api.amivu.com.br/v1/contacts \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "phone": "+5511999999999",
    "external_id": "customer_8291"
  }'

Depois: abra a conversa

curl https://api.amivu.com.br/v1/conversations \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "cnt_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "external_id": "pedido-8291"
  }'

Envie a mensagem

Note o que não aparece aqui: nenhuma menção a canal. Quem sabe por onde falar é a conversa.

O Idempotency-Key não é opcional na prática

Se a rede cair antes da resposta chegar, você não tem como saber se a mensagem saiu. Com a chave, repetir a chamada devolve a mesma mensagem em vez de mandar duas — e o cliente não recebe o aviso duplicado. Veja Idempotência.

Terminal

curl https://api.amivu.com.br/v1/messages \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8291-saiu-para-entrega" \
  -d '{
    "conversation_id": "conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "type": "text",
    "text": "Olá, João! Seu pedido saiu para entrega."
  }'

Resposta

{
  "object": "message",
  "id": "msg_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "conversation_id": "conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "direction": "outbound",
  "type": "text",
  "text": "Olá, João! Seu pedido saiu para entrega.",
  "status": "queued",
  "created_at": "2026-08-26T21:42:19.238Z"
}

Receba o webhook

Cadastre um endpoint para saber quando o cliente responder. Para experimentar sem expor um servidor, um túnel local serve.

A resposta traz o secret inteiro — a única vez. Use-o para conferir a assinatura de cada entrega.

No painel, em Desenvolvedores → Webhooks, o botão Enviar teste dispara uma entrega real e assinada — sem esperar um evento de verdade.

Terminal

curl https://api.amivu.com.br/v1/webhooks \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-tunel.exemplo/webhooks/amivu",
    "events": ["message.received", "message.delivered"]
  }'

Depois disso

Ciclo de vida da mensagem — o que significa queued, e por que status pode ser null.
Canais e capacidades — o que cada conexão aceita.
Erros — o formato único e o que fazer com cada código.
Referência completa — todas as rotas.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.