Símbolo da AmivuSímbolo da AmivuDevelopers

Changelog

O que mudou na API, em ordem.

Mudanças retrocompatíveis entram sem aviso e aparecem aqui. Quebras não acontecem dentro de uma versão — veja Versões e depreciação.

Grupos do WhatsApp e menções

Adicionado

  • `GET /v1/channels/{channel_id}/groups`: os grupos do WhatsApp pareado por QR Code que já têm conversa na Amivu, com o nome, a quantidade de participantes e o `conversation_id`. Alcance `conversations:read`. O id do grupo tem o prefixo `grp_`.
  • `POST /v1/messages` manda para um grupo pelo `conversation_id` da conversa dele ou pelo `group_id`, em texto e em mídia com legenda. Texto e mídia pedem exatamente um dos dois.
  • No grupo, `mention_all: true` marca todos os participantes sem escrever nenhum `@` no texto, e `mentions` marca os telefones da lista. O `@` seguido de um desses telefones no texto vira a menção que o WhatsApp mostra.
  • A conversa traz `is_group` e `group_id`, no `GET` e nos webhooks, e `GET /v1/conversations` filtra por `is_group`.
  • O canal traz `capabilities.groups`: verdadeiro só no WhatsApp pareado por QR Code.
  • Erros `group_not_found`, `channel_without_groups`, `mentions_not_allowed`, `mention_not_in_group` e `group_participants_unavailable`.
  • No servidor MCP, a ferramenta `list_channel_groups` e, em `send_message`, os argumentos `group_id`, `mention_all` e `mentions`; `list_conversations` filtra por `is_group`.

Formulários pela API

Adicionado

  • Formulários (plugin Formulários): `GET /v1/forms` e `GET /v1/forms/{form_id}`, com as perguntas da versão publicada; `GET /v1/forms/{form_id}/responses` e `GET /v1/forms/{form_id}/responses/{response_id}`, com as respostas pela `key` de cada pergunta; e `POST /v1/forms/{form_id}/responses`, que responde como o link e roda as ações do formulário. Alcances `forms:read` e `forms:write`.
  • Evento `form.response.submitted`, com `data.form_response` e `data.contact`, para toda resposta, venha de onde vier.
  • Erros `form_not_found`, `form_response_not_found`, `plugin_not_installed` e `form_closed`.
  • Na automação, o gatilho `form-submitted` (com `trigger: form_submitted` na leitura), a condição `form-answer` e a ação `send-form`, com o formulário pelo id `frm_…`.
  • As ferramentas `list_forms`, `get_form` e `list_form_responses` no servidor MCP.

Melhorado

  • O campo personalizado traz o formato em `type` (`number`, `currency`, `date`, `single_select`, `multi_select`, `boolean`, além de `text`) e as opções em `options`. O valor no contato continua texto.

Canais, automações e a Ami pela API

Adicionado

  • `PATCH /v1/channels/{channel_id}`: renomear o canal e ligar ou desligar a Ami respondendo sozinha nele (`ami_auto_reply`, que passa a vir em todo canal), com `channels:write`.
  • Automações: `GET`, `POST`, `PATCH` e `DELETE` em `/v1/automations`, com `automations:read` e `automations:write`. O fluxo vai em `definition`, no formato que o construtor do painel grava, com os ids públicos de etiqueta, time, campo, canal e pessoa. A automação criada nasce desligada, a menos que o corpo traga `enabled: true`. A lista vem sem o fluxo; ele vem ao ler uma automação.
  • A Ami: `GET` e `PATCH` em `/v1/ami/settings`, e criar, listar, atualizar e apagar em `/v1/ami/roles` e `/v1/ami/knowledge`, com `ami:read` e `ami:write`.
  • As mesmas rotas como ferramentas no servidor MCP, para o assistente configurar canais, automações e a Ami conversando.
  • Erros `live_key_required`, `automation_not_found`, `ami_role_not_found` e `ami_knowledge_not_found`.

Melhorado

  • Canais, automações e a Ami não têm sandbox: a chave de sandbox lê, e mudar volta `403 live_key_required`.
  • O fluxo da automação é recusado com `422` quando repete id de bloco ou de ligação, tem texto acima de 4096 caracteres, chama webhook fora de `https` ou na rede interna, ou faz um laço que não volta por uma opção de pergunta.

Corrigido

  • Texto com o caractere NUL (`\u0000`), no corpo ou na query, era `500`. Agora é `422 invalid_request`, com o campo em `param`.
  • Corpo JSON com mais de 128 níveis aninhados agora é o `400` de JSON inválido.

O servidor MCP também escreve

Adicionado

  • Ferramentas de escrita em `https://mcp.amivu.com.br`: criar, atualizar e apagar contato e pôr e tirar etiqueta dele; abrir conversa, mudar a situação, encerrar, reabrir, atribuir e tirar o responsável; pôr e tirar etiqueta da conversa; escrever nota interna; mandar mensagem de texto; criar time, etiqueta e campo personalizado; atualizar e apagar etiqueta; listar, criar, atualizar e apagar webhook. Cada uma é a rota da API com o mesmo nome, com o alcance dela — ver a página Servidor MCP, na seção IA.
  • Cada ferramenta declara se só lê, se muda ou apaga o que existe e se fala com alguém de fora, para o cliente pedir confirmação antes de escrever.

Melhorado

  • O erro de uma ferramenta traz o argumento que a rota recusou (`param`), além da mensagem e do código.

Criar contato acha quem já está na base pelo telefone

Melhorado

  • `POST /v1/contacts` passou a ser encontre ou crie também pelo telefone: procura a pessoa pelo `external_id`, depois pelo `phone` (em qualquer formato, e no celular com ou sem o nono dígito) e, só quando não vem telefone, pelo `email`. Antes só o `external_id` achava alguém, e o mesmo telefone mandado de novo criava outro contato.
  • Quem é achado é atualizado com os campos que vieram, e a resposta continua `201` com o mesmo contato. Etiquetas e campos personalizados são somados aos que ele já tem, nunca tirados; o telefone de quem foi achado pelo telefone fica como estava, e o `external_id` só é gravado no contato que ainda não tem um. Antes, o contato achado pelo `external_id` voltava sem alteração.
  • Um `external_id` que ainda não está na base declara outra pessoa: o telefone e o e-mail só acham contato sem `external_id`. Duas pessoas com o telefone da empresa continuam separadas quando cada uma tem o seu.
  • Dois envios da mesma pessoa ao mesmo tempo terminam num contato só.

Etiqueta de origem nos canais e nas Entradas

Adicionado

  • Quem chega por um canal ou uma Entrada com etiqueta de origem ganha a etiqueta e gera um `tag.added`, como em qualquer etiqueta. A etiqueta posta de uma vez em quem já tinha chegado antes não gera aviso.

Etiquetas do contato sem substituir a lista

Adicionado

  • `POST /v1/contacts/{id}/tags` (alcance `contacts:write`): acrescenta etiquetas ao contato e mantém as que ele já tem. A que ele já carrega é ignorada, então repetir a chamada não muda nada; uma etiqueta que não existe na organização recusa a chamada inteira com `404 tag_not_found`. Antes, o único jeito era o `tags` do `PATCH /v1/contacts/{id}`, que substitui a lista.
  • `DELETE /v1/contacts/{id}/tags/{tag_id}` (alcance `contacts:write`): tira uma etiqueta do contato e mantém as outras.

A conversa em andamento fica em andamento no chat do site

Corrigido

  • Chat do site: a mensagem do visitante numa conversa `pending` a devolvia para `open`. Agora só a conversa `closed` volta para `open` quando o contato escreve, como já acontecia no WhatsApp; a `pending` continua `pending`, com o mesmo responsável.
  • Chat do site: cada mensagem do visitante numa conversa que não está encerrada passa a gerar `conversation.updated`, como a mensagem que chega pelo WhatsApp já gerava.

Mídia pela API, e capacidades que dizem a verdade

Adicionado

  • `POST /v1/uploads`: sobe um arquivo (multipart, campo `file`) e devolve um anexo `att_…`, válido para a organização e o ambiente da chave até `expires_at`. Mesmos tipos e mesmo limite do painel.
  • `POST /v1/messages` envia `type` `image`, `video`, `audio` e `document` com `attachment_id`, pelo mesmo caminho de envio do painel. `type: "template"` continua recusado com `422 unsupported_message_type`.
  • Código de erro `attachment_type_mismatch` (422): o `type` pedido não é o do arquivo anexado.
  • `GET /v1/attachments/{id}/content` (alcance `messages:read`): baixa o arquivo de um anexo com a chave de API — o subido e a mídia das mensagens, inclusive a recebida do cliente.

Corrigido

  • `attachment.url` — nas mensagens, no `message.received` e nos demais webhooks — trazia o caminho interno de mídia do painel, que a chave de API não alcança. Agora é o endereço absoluto de `GET /v1/attachments/{id}/content`. O tipo do campo não mudou; quem montava a URL à mão a partir do caminho antigo deve passar a usar o valor como veio.
  • `GET /v1/channels`: o chat do site passou a declarar só `text` em `capabilities`. Imagem, áudio, vídeo e documento apareciam como suportados, mas o widget nunca os entregou ao visitante — mídia numa conversa do chat do site agora volta `422 unsupported_message_type`.
  • O escopo `messages:write` descreve o que a API faz: texto e mídia (com o upload do anexo), e ainda não modelo aprovado.

A API pública, v1

Adicionado

  • Contatos, conversas, mensagens, canais, atendentes, times, etiquetas, notas e campos personalizados.
  • Webhooks com assinatura HMAC-SHA-256, reentrega com recuo e depurador de entregas no painel.
  • Chaves de API com escopos granulares, e ambiente de teste isolado no banco.
  • Idempotência por `Idempotency-Key` em mensagens, contatos e conversas.
  • Paginação por cursor, limite por organização e `X-Amivu-Request-Id` em toda resposta.
  • Especificação OpenAPI 3.1 em `api.amivu.com.br/v1/openapi.json`.

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