Símbolo da AmivuSímbolo da AmivuDevelopers

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

Esta tabela é gerada do código
Os valores abaixo saem da mesma função que a API usa para decidir se o canal aceita um tipo de mensagem. Ela não pode prometer o que o canal não faz — nem esconder o que ele faz.
RecursoWhatsApp oficialWhatsApp pareadoChat do siteInstagramMessengerE-mail
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.

O que a API envia, por canal
Texto e mídia saem por 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

Terminal
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
  }
}
Nunca esperamos que você adivinhe
Se o seu código precisa saber se pode mandar um modelo, leia 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.

Terminal
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.

A lista é dos grupos que a Amivu já viu
Um grupo entra na lista quando vira conversa: pelo histórico importado ao parear o número, ou pela primeira mensagem depois disso. Grupo em que o número está e onde ninguém escreveu desde então ainda não aparece — basta uma mensagem nele.

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.

Terminal
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.

Só com a chave de produção
O canal é um só para os dois ambientes. Por isso a chave de sandbox lê, mas mudar volta 403 live_key_required.

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