Canais e capacidades
O que cada conexão consegue fazer, e como perguntar antes de tentar.
A API é unificada; os canais não são. Um envia modelo aprovado, outro não; um confirma leitura, outro nem entrega. A matriz de capacidades é como você descobre isso sem tentar.
A matriz de capacidades
| Recurso | WhatsApp oficial | WhatsApp pareado | Chat do site | Messenger | ||
|---|---|---|---|---|---|---|
| Texto | ✓ | ✓ | ✓ | — | — | — |
| Imagem | ✓ | ✓ | — | — | — | — |
| Vídeo | ✓ | ✓ | — | — | — | — |
| Áudio | ✓ | ✓ | — | — | — | — |
| Documento | ✓ | ✓ | — | — | — | — |
| Modelo aprovado | ✓ | — | — | — | — | — |
| Botões | — | — | — | — | — | — |
| Localização | — | — | — | — | — | — |
| Recibo de entrega | ✓ | ✓ | ✓ | — | — | — |
| Recibo de leitura | ✓ | ✓ | — | — | — | — |
| Janela de atendimento | ✓ | — | — | — | — | — |
| Grupos | — | ✓ | — | — | — | — |
Instagram, Messenger e e-mail aparecem com tudo em —: eles existem no modelo para que conectá-los depois não exija mudança de contrato, e hoje não têm adaptador de envio. A tabela diz isso em vez de prometer texto e falhar na primeira chamada.
O chat do site troca só texto, nos dois sentidos: o widget não envia anexo, e uma mídia mandada pelo painel não aparece para o visitante.
POST /v1/messages onde a matriz diz que o canal os transporta — a mídia com um anexo subido antes em POST /v1/uploads (ver Anexos e mídia). Modelo aprovado é a exceção: mesmo marcado no WhatsApp oficial, ele ainda volta 422 unsupported_message_type pela API. Quando isso mudar, entra no changelog.Como perguntar
curl https://api.amivu.com.br/v1/channels \
-H "Authorization: Bearer $AMIVU_API_KEY"
{
"object": "channel",
"id": "chn_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
"name": "WhatsApp Comercial",
"type": "whatsapp",
"provider": "meta",
"status": "connected",
"display_number": "+55 15 99110-5435",
"ami_auto_reply": true,
"capabilities": {
"text": true,
"image": true,
"template": true,
"buttons": false,
"delivery_receipts": true,
"read_receipts": true,
"session_window": true
}
}
capabilities.template — não deduza pelo type. É exatamente para isso que este campo existe.WhatsApp são dois
O provider distingue duas conexões que se chamam “WhatsApp” e não são a mesma coisa:
meta— a Cloud API oficial. Tem modelo aprovado e a janela de 24 horas fora da qual só modelo passa.whatsapp_web— uma sessão pareada por QR Code. Manda texto e mídia, não tem modelo e não tem janela, e é a única que participa de grupos.
Tratar os dois como iguais é o erro que mais custa aqui: um código que mande type: "template" sem olhar o provedor funciona num cliente e falha no vizinho.
status também importa. Um canal disconnected ou disabled recusa envio com 422 channel_not_connected — e o caminho de volta é o painel, não uma retentativa.
No chat do site, disabled é o chat desligado por quem administra a conta: ele sai dos sites onde está instalado, e a configuração e as conversas continuam. Ligado de novo no painel, o canal volta como estava, com a mesma chave.
Os grupos de um número
Onde capabilities.groups é verdadeiro, o número participa de grupos, e GET /v1/channels/{channel_id}/groups lista os dele, do mais novo para o mais antigo, com conversations:read. Em qualquer outro canal a resposta é 422 channel_without_groups.
curl "https://api.amivu.com.br/v1/channels/chn_01K7ZFA5X8Q2M4N6P8R0T2V4W6/groups?limit=50" \
-H "Authorization: Bearer $AMIVU_API_KEY"
{
"object": "list",
"data": [
{
"object": "group",
"id": "grp_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
"conversation_id": "conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
"channel": {
"id": "chn_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
"type": "whatsapp",
"provider": "whatsapp_web"
},
"name": "Clientes VIP",
"participant_count": 42,
"last_message_at": "2026-11-20T13:05:00.000Z",
"created_at": "2026-10-02T18:40:12.000Z"
}
],
"pagination": { "has_more": false, "next_cursor": null }
}
O id do grupo é o group_id que o envio de mensagem aceita, e o mesmo grupo aparece em GET /v1/conversations com is_group: true. participant_count é a contagem da última vez que o canal leu o grupo, e vem null enquanto ele não leu.
Renomear e ligar a Ami
PATCH /v1/channels/{channel_id} muda duas coisas, com channels:write: o nome e se a Ami responde sozinha neste canal (ami_auto_reply). Conectar, parear e desconectar continuam no painel, porque passam pelo login no provedor.
curl -X PATCH https://api.amivu.com.br/v1/channels/chn_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
-H "Authorization: Bearer $AMIVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "ami_auto_reply": false }'
A resposta sozinha precisa estar ligada também na conta, em a configuração da Ami: o canal só diz onde ela vale.
403 live_key_required.Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.