Todas as rotas

Gerada da mesma especificação que a API valida.

Todas as rotas de https://api.amivu.com.br/v1. Esta página e o openapi.json saem do mesmo catálogo — se divergirem, o CI reprova antes de qualquer coisa subir.

Prefere disparar do seu cliente de API?

A coleção sai deste mesmo catálogo — todas as 42 rotas, agrupadas, com o cabeçalho de autorização pronto. A chave fica em branco: preencha amivu_api_key no seu cliente.

Baixar coleção OpenAPI

O arquivo é uma coleção Postman v2.1 — que o Insomnia, o Bruno e o Hoppscotch também importam. Se o seu cliente prefere especificação, aponte-o direto para o openapi.json.

Use uma chave de sandbox

Com uma chave amivu_live_…, toda mensagem disparada da coleção chega a um cliente de verdade. O sandbox aceita as mesmas rotas e não envia para ninguém.

Experimente sem sair daqui

Cada rota tem um botão Testar. A chave que você digitar fica só no seu navegador: a requisição sai daqui direto para a API, sem passar por nenhum servidor nosso, e o valor nunca é guardado.

Contatos

GET/contactsscope contacts:read

Returns the organization's contacts, newest first. Filter by `email`, `phone` or `external_id` to find a specific person without paging through the whole base.

Parâmetros de consulta

limitnumber
afterstring
emailstring
phonestring
external_idstring
querystring
tag_idstring
created_afterstring
created_beforestring

Resposta

200 — uma lista de Contact, com pagination.

Exemplo

Terminal

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

POST/contactsscope contacts:writeaccepted Idempotency-Key

Creates a contact. When `external_id` is provided and already exists, the existing contact is returned unchanged — which makes CRM synchronisation safe to re-run.

Corpo da requisição

namestring
first_namestring
last_namestring
emailstring
phonestring
external_idstring
avatar_urlstring
tagsstring[]
custom_fieldsobject
metadataobject

Resposta

201 — um objeto Contact.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/contacts \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

GET/contacts/{contact_id}scope contacts:read

Returns a single contact, with its tags and custom fields.

Parâmetros de caminho

contact_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Contact.

Exemplo

Terminal

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

PATCH/contacts/{contact_id}scope contacts:write

Updates the given fields. Sending `tags` REPLACES the contact's tags; sending `null` in a custom field clears it.

Parâmetros de caminho

contact_id — o identificador Amivu, com prefixo.

Corpo da requisição

namestring
first_namestring
last_namestring
emailstring
phonestring
external_idstring
avatar_urlstring
tagsstring[]
custom_fieldsobject
metadataobject

Resposta

200 — um objeto Contact.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/contacts/cnt_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -X PATCH \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

DELETE/contacts/{contact_id}scope contacts:write

Deletes the contact and, in cascade, the conversations and messages exchanged with that person. This cannot be undone.

Parâmetros de caminho

contact_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Deleted.

Exemplo

Terminal

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

Conversas

GET/conversationsscope conversations:read

Returns conversations, newest first, filterable by status, channel and assignee.

Parâmetros de consulta

limitnumber
afterstring
status"open" | "pending" | "closed"
channel_idstring
channel_type"whatsapp" | "instagram" | "messenger" | "email" | "webchat"
contact_idstring
assigned_tostring
team_idstring
tag_idstring
external_idstring
created_afterstring
created_beforestring
updated_afterstring

Resposta

200 — uma lista de Conversation, com pagination.

Exemplo

Terminal

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

POST/conversationsscope conversations:writeaccepted Idempotency-Key

Opens a conversation with a contact. When `external_id` is provided and already exists, the existing conversation is returned — so a retry does not split the history in two.

Corpo da requisição

contact_idstringobrigatório
channel_idstring
external_idstring
metadataobject

Resposta

201 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

GET/conversations/{conversation_id}scope conversations:read

Returns a single conversation.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

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

PATCH/conversations/{conversation_id}scope conversations:write

Updates status, `external_id` or `metadata`.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Corpo da requisição

status"open" | "pending" | "closed"
external_idstring
metadataobject

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -X PATCH \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

POST/conversations/{conversation_id}/closescope conversations:write

Marks the conversation as resolved and stamps the time it happened.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6/close \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY"

POST/conversations/{conversation_id}/reopenscope conversations:write

Brings a closed conversation back to `open`.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6/reopen \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY"

POST/conversations/{conversation_id}/assignscope conversations:write

Assigns the conversation to an agent or a team. The agent must belong to this organization — assigning across organizations is refused.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Corpo da requisição

user_idstring
team_idstring

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6/assign \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

POST/conversations/{conversation_id}/unassignscope conversations:write

Removes the current assignee.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6/unassign \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY"

GET/conversations/{conversation_id}/messagesscope messages:read

Returns the conversation's messages, newest first.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Parâmetros de consulta

limitnumber
afterstring
direction"inbound" | "outbound"
created_afterstring
created_beforestring

Resposta

200 — uma lista de Message, com pagination.

Exemplo

Terminal

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

GET/conversations/{conversation_id}/notesscope notes:read

Returns the conversation's internal notes. Notes are never delivered to the contact — they are a different entity from messages, with no send path at all.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Resposta

200 — uma lista de Note, com pagination.

Exemplo

Terminal

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

POST/conversations/{conversation_id}/notesscope notes:write

Adds an internal note. It stays inside Amivu.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Corpo da requisição

bodystringobrigatório

Resposta

201 — um objeto Note.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6/notes \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

POST/conversations/{conversation_id}/tagsscope tags:write

Applies a tag to the conversation's CONTACT — the only tag link the domain has. The tag follows the person across every conversation, filter and broadcast.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.

Corpo da requisição

tag_idstringobrigatório

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6/tags \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

DELETE/conversations/{conversation_id}/tags/{tag_id}scope tags:write

Removes the tag from the conversation's contact.

Parâmetros de caminho

conversation_id — o identificador Amivu, com prefixo.
tag_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Conversation.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/conversations/conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6/tags/tag_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -X DELETE \
  -H "Authorization: Bearer $AMIVU_API_KEY"

Mensagens

POST/messagesscope messages:writeaccepted Idempotency-Key

Sends a message through the conversation's channel. The channel is derived from the conversation — there is no per-channel endpoint. Capabilities are checked before anything is written: a channel that does not support the type refuses with `unsupported_message_type` and nothing is recorded. Text and media are sent: for `image`, `video`, `audio` and `document`, upload the file first with `POST /uploads` and pass its `attachment_id`. `template` is part of the schema but is not sent yet — it is refused with `unsupported_message_type` on every channel.

Corpo da requisição

conversation_idstringobrigatório
type"text"obrigatório
textstring
metadataobject
attachment_idstring
templateobject

Resposta

201 — um objeto Message.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/messages \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

GET/messages/{message_id}scope messages:read

Returns a message and its delivery state. `status` may be `null` — that is information, not absence of it: the channel does not report receipts.

Parâmetros de caminho

message_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Message.

Exemplo

Terminal

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

Canais

GET/channelsscope channels:read

Returns the connected channels and what each one can do. Read `capabilities` before sending — it is generated from the implementation, not from the provider's brochure.

Resposta

200 — uma lista de Channel, com pagination.

Exemplo

Terminal

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

GET/channels/{channel_id}scope channels:read

Returns one channel, with its capability matrix.

Parâmetros de caminho

channel_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Channel.

Exemplo

Terminal

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

Atendentes

GET/usersscope users:read

Returns the organization's agents.

Parâmetros de consulta

limitnumber
afterstring

Resposta

200 — uma lista de User, com pagination.

Exemplo

Terminal

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

GET/users/{user_id}scope users:read

Returns one agent.

Parâmetros de caminho

user_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto User.

Exemplo

Terminal

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

Times

GET/teamsscope teams:read

Returns the organization's teams.

Resposta

200 — uma lista de Team, com pagination.

Exemplo

Terminal

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

POST/teamsscope teams:write

Creates a team.

Corpo da requisição

namestringobrigatório

Resposta

201 — um objeto Team.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/teams \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

GET/teams/{team_id}scope teams:read

Returns one team.

Parâmetros de caminho

team_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Team.

Exemplo

Terminal

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

GET/teams/{team_id}/usersscope teams:read

Returns the agents that belong to the team.

Parâmetros de caminho

team_id — o identificador Amivu, com prefixo.

Resposta

200 — uma lista de User, com pagination.

Exemplo

Terminal

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

Etiquetas

GET/tagsscope tags:read

Returns the organization's tags.

Resposta

200 — uma lista de Tag, com pagination.

Exemplo

Terminal

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

POST/tagsscope tags:write

Creates a tag.

Corpo da requisição

namestringobrigatório
colorstring

Resposta

201 — um objeto Tag.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/tags \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

PATCH/tags/{tag_id}scope tags:write

Renames the tag or changes its colour.

Parâmetros de caminho

tag_id — o identificador Amivu, com prefixo.

Corpo da requisição

namestring
colorstring

Resposta

200 — um objeto Tag.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/tags/tag_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -X PATCH \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

DELETE/tags/{tag_id}scope tags:write

Deletes the tag; it disappears from every contact that had it.

Parâmetros de caminho

tag_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Deleted.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/tags/tag_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -X DELETE \
  -H "Authorization: Bearer $AMIVU_API_KEY"

Campos personalizados

GET/custom-fieldsscope custom_fields:read

Returns the custom field catalogue. The `key` of each field is what appears in `contact.custom_fields`, and it never changes after creation.

Resposta

200 — uma lista de CustomField, com pagination.

Exemplo

Terminal

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

POST/custom-fieldsscope custom_fields:write

Creates a custom field definition.

Corpo da requisição

namestringobrigatório
keystring
scope"contact" | "organization"
valuestring

Resposta

201 — um objeto CustomField.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/custom-fields \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

Webhooks

GET/webhooksscope webhooks:read

Returns the endpoints registered for THIS key's environment. Secrets come masked.

Resposta

200 — uma lista de WebhookEndpoint, com pagination.

Exemplo

Terminal

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

POST/webhooksscope webhooks:write

Registers an endpoint. The signing secret comes in full in this response and never again — store it before you move on. The endpoint's environment is taken from the API key, not from the body.

Corpo da requisição

urlstringobrigatório
descriptionstring
events"message.received" | "message.sent" | "message.delivered" | "message.read" | "message.failed" | "conversation.created" | "conversation.updated" | "conversation.assigned" | "conversation.closed" | "conversation.reopened" | "contact.created" | "contact.updated" | "tag.added" | "tag.removed"[]obrigatório
environment"live" | "test"
enabledboolean

Resposta

201 — um objeto WebhookEndpoint.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

GET/webhooks/{webhook_id}scope webhooks:read

Returns one endpoint, with the secret masked.

Parâmetros de caminho

webhook_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto WebhookEndpoint.

Exemplo

Terminal

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

PATCH/webhooks/{webhook_id}scope webhooks:write

Updates the URL, description, subscribed events or enabled state. Re-enabling clears the failure counter.

Parâmetros de caminho

webhook_id — o identificador Amivu, com prefixo.

Corpo da requisição

urlstring
descriptionstring
events"message.received" | "message.sent" | "message.delivered" | "message.read" | "message.failed" | "conversation.created" | "conversation.updated" | "conversation.assigned" | "conversation.closed" | "conversation.reopened" | "contact.created" | "contact.updated" | "tag.added" | "tag.removed"[]
enabledboolean

Resposta

200 — um objeto WebhookEndpoint.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/webhooks/wh_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -X PATCH \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

DELETE/webhooks/{webhook_id}scope webhooks:write

Deletes the endpoint and its delivery history.

Parâmetros de caminho

webhook_id — o identificador Amivu, com prefixo.

Resposta

200 — um objeto Deleted.

Exemplo

Terminal

curl https://api.amivu.com.br/v1/webhooks/wh_01K7ZFA5X8Q2M4N6P8R0T2V4W6 \
  -X DELETE \
  -H "Authorization: Bearer $AMIVU_API_KEY"

GET/webhooks/{webhook_id}/deliveriesscope webhooks:read

Returns one row per ATTEMPT, newest first. Attempts of the same event share `event_id` — which is also what you should deduplicate on when receiving.

Parâmetros de caminho

webhook_id — o identificador Amivu, com prefixo.

Resposta

200 — uma lista de WebhookDelivery, com pagination.

Exemplo

Terminal

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

Precisa gerar um cliente? Baixe a especificação — ela é OpenAPI 3.1 e funciona com os geradores de sempre. Veja também Versões e depreciação.

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