API do Evolua Chat — Documentação

Introdução

A API REST do Evolua Chat expõe as mesmas funcionalidades que você usa no painel. Toda requisição é feita por HTTPS, envia e recebe JSON e é autenticada com um token criado dentro da sua própria conta.

Os dados retornados são sempre os da sua conta: contatos, conversas, etiquetas, funis e usuários que pertencem a ela. Não é possível acessar dados de outras contas com o seu token.

O que dá para fazer

Cadastrar contatos vindos do seu site, formulário ou checkout.
Abrir uma conversa e disparar a primeira mensagem no WhatsApp.
Marcar contatos com etiquetas conforme o comportamento deles.
Criar e mover cards no funil quando um negócio avança.
Distribuir conversas entre atendentes e equipes automaticamente.

Como ler os exemplos

Todos os exemplos usam cURL. Substitua tk_seu_token_aqui pelo token gerado na sua conta e troque os IDs de exemplo pelos seus. Onde aparece :id no caminho, envie o número diretamente — por exemplo /api/contacts/123.

Autenticação

Toda requisição precisa do token no cabeçalho Authorization. Sem ele, a API responde 401 Unauthorized.

Header

Authorization: Bearer tk_seu_token_aqui

Criar seu token

Entre no painel do Evolua Chat com um usuário administrador.
Abra o menu Integração.
Clique em criar um novo token da API.
Copie o token na hora — ele aparece uma única vez.
Guarde o token no gerenciador de segredos da sua automação.

Guarde o token com cuidado. Ele dá acesso aos dados da sua conta e não pode ser recuperado depois de fechado. Se perder ou vazar, crie um novo e apague o antigo.

Você pode manter vários tokens ativos, um para cada integração — assim é possível revogar um sem derrubar os outros.
O token pode ser permanente ou ter validade de 12, 24 ou 48 meses.
O token carrega as permissões do usuário que o criou. Alguns endpoints exigem perfil ADMIN.
Nunca coloque o token em código de frontend, HTML público ou repositório aberto.

Testando a conexão

Este é o teste mais rápido para saber se o token está válido. Se responder 200, está tudo certo.

cURL

curl -X GET https://app.evoluachat.com.br/api/contacts \
  -H "Authorization: Bearer tk_seu_token_aqui"

Integração com n8n

No n8n você não precisa de node específico: use o node HTTP Request apontando para os endpoints desta página. A configuração abaixo serve para qualquer chamada.

Criar a credencial de autenticação

Em Credentials, crie uma credencial do tipo Header Auth.
No campo Name, escreva Authorization.
No campo Value, escreva Bearer tk_seu_token_aqui.
Salve com um nome que identifique a conta, por exemplo “Evolua Chat — produção”.

Configurar o node HTTP Request

Campo	Valor
Method	GET, POST, PUT ou DELETE, conforme o endpoint
URL	`https://app.evoluachat.com.br/api/...`
Authentication	Generic Credential Type → Header Auth → sua credencial
Send Body	Ativado nas chamadas POST e PUT
Body Content Type	JSON
Send Query Parameters	Ativado quando o endpoint aceita filtros

Fluxo pronto: lead do formulário vira conversa

Um encadeamento comum, usando três nodes HTTP Request em sequência:

POST /api/contacts — cria o contato com nome e telefone recebidos do formulário.
POST /api/conversations/start — abre a conversa na inbox escolhida e devolve o conversation_id.
POST /api/conversations/:id/messages — envia a mensagem de boas-vindas usando o ID do passo anterior.

Para reaproveitar contatos que já existem, chame antes GET /api/contacts/number/:phone e siga direto para o passo 2 quando encontrar alguém.

Exemplo de corpo com dados dinâmicos

Nos campos do body, use expressões do n8n para puxar valores do node anterior.

JSON — body do node HTTP Request

{
  "name": "{{ $json.nome }}",
  "phone": "{{ $json.telefone }}",
  "email": "{{ $json.email }}"
}

Antes de disparar em massa, confira o limite de requisições e ative “Retry On Fail” no node para tratar erros temporários sem perder o lead.

Outras ferramentas

A mesma lógica vale para Make, Zapier, Pipedream ou qualquer linguagem: um cabeçalho Authorization, corpo em JSON e a URL base acima.

Listar contatos

GET/api/contacts

Retorna os contatos da conta com busca, filtros e paginação.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`search`	string	Não	Busca por nome, telefone ou e-mail ao mesmo tempo
`archived`	boolean	Não	Filtra arquivados (`true` ou `false`)
`blocked`	boolean	Não	Filtra bloqueados (`true` ou `false`)
`gender`	string	Não	`M` ou `F`
`date_filter`	string	Não	`this_month`, `last_month`, `last_30_days`, `last_90_days`, `this_year` ou `custom`
`date_from`	string	Não	Data inicial (AAAA-MM-DD), com `date_filter=custom`
`date_to`	string	Não	Data final (AAAA-MM-DD), com `date_filter=custom`
`include_labels`	array	Não	IDs de etiquetas separados por vírgula
`exclude_labels`	array	Não	IDs de etiquetas a excluir do resultado
`page`	integer	Não	Página desejada (padrão 1)
`limit`	integer	Não	Itens por página (máximo e padrão 50)

cURL

curl -X GET "https://app.evoluachat.com.br/api/contacts?search=joão&page=1&limit=50" \
  -H "Authorization: Bearer tk_seu_token_aqui"

JavaScript

const res = await fetch(
  "https://app.evoluachat.com.br/api/contacts?page=1&limit=50",
  { headers: { Authorization: "Bearer tk_seu_token_aqui" } }
);
const { data, pagination } = await res.json();

Python

import requests

url = "https://app.evoluachat.com.br/api/contacts"
headers = {"Authorization": "Bearer tk_seu_token_aqui"}
resposta = requests.get(url, headers=headers, params={"page": 1, "limit": 50})
print(resposta.json())

Resposta 200

JSON

{
  "data": [
    {
      "id": 1,
      "name": "João Silva",
      "phone": "+5511999999999",
      "email": "joao@example.com",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 100,
    "totalPages": 2
  }
}

Para percorrer todos os contatos, repita a chamada aumentando page até alcançar pagination.totalPages.

Criar contato

POST/api/contacts

Cadastra um contato novo na conta.

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do contato
`phone`	string	Sim	Telefone com código do país
`email`	string	Não	E-mail do contato

cURL

curl -X POST https://app.evoluachat.com.br/api/contacts \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Santos",
    "phone_e164": "+5511888888888",
    "email": "maria@example.com"
  }'

Envie o telefone no padrão internacional, com o + e o código do país: +5511999999999. Números sem DDI podem não encontrar a conversa correta no WhatsApp.

Buscar contato por número

GET/api/contacts/number/:phone

Encontra um contato pelo telefone. Use antes de criar um cadastro para não duplicar a base.

Parâmetro do caminho

Parâmetro	Tipo	Descrição
`phone`	string	Telefone apenas com números, com ou sem DDI

cURL

curl -X GET "https://app.evoluachat.com.br/api/contacts/number/5511999999999" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "id": 123,
  "name": "João Silva",
  "last_name": "Silva",
  "phone_e164": "5511999999999",
  "email": "joao@email.com",
  "country_code": "+55",
  "gender": "M",
  "data_nascimento": "1990-01-15",
  "blocked": false,
  "archived": false,
  "created_at": "2026-01-08T10:00:00.000Z",
  "labels": [
    { "id": 1, "name": "VIP", "color": "#ff0000" }
  ],
  "custom_fields": {
    "empresa": "Acme Corp",
    "cargo": "Gerente"
  },
  "last_conversation_id": 456
}

Erros

Código	Mensagem	O que fazer
`400`	Telefone é obrigatório	Informe o número no caminho da URL
`404`	Contato não encontrado	Nenhum contato com esse número — crie o cadastro

Buscar contato por ID

GET/api/contacts/:id

Retorna o cadastro completo do contato, incluindo etiquetas, campos personalizados e o ID da conversa mais recente.

cURL

curl -X GET "https://app.evoluachat.com.br/api/contacts/123" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "id": 123,
  "name": "João Silva",
  "last_name": "Silva",
  "phone_e164": "5511999999999",
  "email": "joao@email.com",
  "country_code": "+55",
  "gender": "M",
  "data_nascimento": "1990-01-15",
  "blocked": false,
  "archived": false,
  "created_at": "2026-01-08T10:00:00.000Z",
  "labels": [
    { "id": 1, "name": "VIP", "color": "#ff0000" }
  ],
  "custom_fields": {
    "empresa": "Acme Corp"
  },
  "last_conversation_id": 456
}

O campo last_conversation_id traz a conversa mais recente do contato, ou null quando ainda não houve nenhuma. Use esse número para enviar mensagens sem precisar abrir uma conversa nova.

Listar tags do contato

GET/api/contacts/:id/labels

Retorna todas as etiquetas associadas a um contato.

cURL

curl -X GET "https://app.evoluachat.com.br/api/contacts/42/labels" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "contact_id": 42,
  "tags": [
    { "id": 1, "name": "VIP", "color": "#4CAF50" },
    { "id": 2, "name": "Lead", "color": "#2196F3" }
  ]
}

Erros

Código	Mensagem	O que fazer
`404`	Contato não encontrado	Confira o ID do contato
`500`	Erro interno do servidor	Tente novamente em alguns instantes

Adicionar tag ao contato

POST/api/contacts/:id/labels

Associa uma etiqueta ao contato. Se a etiqueta já estiver aplicada, a resposta continua sendo 200 e nada é duplicado — dá para repetir a chamada com segurança.

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`label_id`	integer	Sim	ID da etiqueta

cURL

curl -X POST "https://app.evoluachat.com.br/api/contacts/42/labels" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "label_id": 5 }'

Resposta 200 — etiqueta aplicada

JSON

{
  "id": 42,
  "name": "João Silva",
  "last_name": "Santos",
  "email": "joao@email.com",
  "phone_e164": "5511999999999",
  "labels": [
    { "id": 5, "name": "Cliente", "color": "#FF9800" }
  ]
}

Resposta 200 — etiqueta já estava aplicada

JSON

{
  "id": 42,
  "name": "João Silva",
  "labels": [],
  "message": "Tag já cadastrada neste contato",
  "already_added": true
}

Erros

Código	Mensagem	O que fazer
`400`	label_id não enviado	Inclua o campo no corpo da requisição
`404`	Contato ou etiqueta não encontrado	Confira os dois IDs
`500`	Erro interno do servidor	Tente novamente em alguns instantes

Remover tag do contato

DELETE/api/contacts/:id/labels/:labelId

Tira a etiqueta do contato. Se ela não estava aplicada, a resposta também é 200.

cURL

curl -X DELETE "https://app.evoluachat.com.br/api/contacts/42/labels/5" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200 — etiqueta removida

JSON

{
  "id": 42,
  "name": "João Silva",
  "labels": []
}

Resposta 200 — etiqueta não estava no contato

JSON

{
  "id": 42,
  "name": "João Silva",
  "labels": [],
  "message": "Tag não está cadastrada naquele contato",
  "not_found_on_contact": true
}

Listar conversas

GET/api/conversations

Lista as conversas da conta com filtros de status, inbox e responsável.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Não	`open`, `pending`, `resolved` ou `all`
`filter`	string	Não	`all`, `mine`, `unassigned` ou `groups`
`inbox_id`	integer ou array	Não	Um ID ou vários IDs de inbox
`assignee_id`	integer ou array	Não	Atendente responsável
`page`	integer	Não	Página desejada (padrão 1)
`limit`	integer	Não	Itens por página (máximo 50)

cURL

curl -X GET "https://app.evoluachat.com.br/api/conversations?status=open&page=1" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Buscar conversa por ID

GET/api/conversations/:id

Traz a conversa com as mensagens, as mensagens fixadas e quem está responsável pelo atendimento.

cURL

curl -X GET "https://app.evoluachat.com.br/api/conversations/456" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "conversation": {
    "id": 456,
    "status": "open",
    "contact_id": 123,
    "contact_name": "João Silva",
    "phone_e164": "5511999999999",
    "profile_picture": "https://...",
    "is_group": false,
    "inbox_id": 1,
    "inbox_name": "WhatsApp Principal",
    "inbox_type": "whatsapp",
    "connection_id": 1,
    "connection_status": "connected",
    "assignee_id": 5,
    "assignee_name": "Maria Atendente",
    "team_id": 2,
    "team_name": "Suporte Técnico",
    "created_at": "2026-01-08T10:00:00.000Z"
  },
  "messages": [],
  "pinnedMessages": [],
  "has_more": false
}

Campos de atribuição

Campo	Tipo	Descrição
`assignee_id`	integer ou null	ID do atendente responsável
`assignee_name`	string ou null	Nome do atendente responsável
`team_id`	integer ou null	ID da equipe responsável
`team_name`	string ou null	Nome da equipe responsável

Quando a conversa ainda não tem responsável, esses quatro campos voltam como null.

Janela de 24 horas (WhatsApp Oficial)

GET/api/conversations/:id/session

Informa se a conversa ainda está dentro da janela de 24 horas do WhatsApp Oficial. A janela abre a cada mensagem que o cliente envia; dentro dela você pode responder com texto e mídia livremente.

Vale apenas para conversas em inbox do tipo whatsapp_cloud.

Resposta 200

JSON

{
  "conversation_id": 123,
  "inbox_id": 12,
  "inbox_type": "whatsapp_cloud",
  "last_customer_message_at": "2026-01-17T12:34:56.000Z",
  "session_open": true,
  "session_expires_at": "2026-01-18T12:34:56.000Z",
  "seconds_remaining": 86399,
  "now": "2026-01-17T12:35:00.000Z"
}

cURL

curl -X GET "https://app.evoluachat.com.br/api/conversations/123/session" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Como usar o resultado

session_open: true — envie a mensagem normalmente por POST /api/conversations/:id/messages.
session_open: false — a janela fechou. Para retomar o contato, envie um template aprovado.

Erros

Código	Mensagem	O que fazer
`400`	ID inválido	Envie o ID numérico da conversa
`400`	Disponível apenas para inbox WhatsApp Oficial	A conversa não é de uma inbox `whatsapp_cloud`
`401`	Unauthorized	Token ausente ou inválido
`403`	Acesso negado	A conversa pertence a outro atendente
`404`	Conversa não encontrada	Confira o ID da conversa

Iniciar conversa por número

POST/api/conversations/start

Abre uma conversa a partir de um telefone. Se já existir conversa do mesmo contato naquela inbox, ela é reaproveitada ou reaberta em vez de duplicar.

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`phone`	string	Sim	Telefone do contato com DDI e DDD. Caracteres não numéricos são removidos e, sem o `+`, ele é adicionado — o país não é assumido automaticamente
`inbox_id`	number	Sim	Inbox onde a conversa será aberta

cURL

curl -X POST "https://app.evoluachat.com.br/api/conversations/start" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511999999999",
    "inbox_id": 12
  }'

Resposta 200

JSON

{
  "conversation_id": 123,
  "contact_id": 456,
  "is_new": true,
  "is_new_contact": true,
  "session_open": true,
  "templates": [],
  "inbox_type": "whatsapp"
}

O que o endpoint faz

Confere se a inbox pertence à conta e normaliza o telefone.
Localiza o contato ou cria um novo.
Cria a conversa, ou reabre a que já existia para aquele contato e inbox.
No WhatsApp Oficial, ainda devolve session_open e os templates disponíveis.

Onde encontrar o inbox_id

Use GET /api/inboxes para listar as inboxes da conta e copiar o ID.

Erros

Código	Mensagem	O que fazer
`400`	phone e inbox_id são obrigatórios	Preencha os dois campos
`401`	Unauthorized	Token ausente ou inválido
`404`	Caixa de entrada não encontrada	A inbox não existe ou não é da sua conta
`409`	conversation_assigned_to_another	O contato já está em atendimento com outro usuário

JSON — exemplo do erro 409

{
  "error": "conversation_assigned_to_another",
  "message": "Este contato já possui uma conversa em andamento com Maria Atendente",
  "assignee_id": 99,
  "assignee_name": "Maria Atendente",
  "conversation_id": 123
}

Enviar mensagem na conversa

POST/api/conversations/:id/messages

Envia uma mensagem de texto ou mídia em uma conversa já aberta.

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`content`	string	Sim	Texto da mensagem, ou legenda quando envia mídia
`type`	string	Não	`text`, `image`, `video`, `document` ou `audio` (padrão `text`)
`media_url`	string	Não	URL pública do arquivo quando `type` não é `text`

cURL — texto

curl -X POST https://app.evoluachat.com.br/api/conversations/123/messages \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Olá! Como posso ajudar?",
    "type": "text"
  }'

cURL — imagem

curl -X POST https://app.evoluachat.com.br/api/conversations/123/messages \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Segue o catálogo de setembro",
    "type": "image",
    "media_url": "https://seusite.com.br/catalogo.jpg"
  }'

Em inbox do WhatsApp Oficial, confira a janela de 24 horas antes de enviar. Fora dela, só passam templates aprovados.

Atribuir conversa

POST/api/conversations/:id/assign

Define quem cuida da conversa: um atendente, uma equipe ou os dois. Envie ao menos um dos campos.

Campos do corpo

Campo	Tipo	Descrição
`assignee_id`	integer ou null	Atendente que assume a conversa
`team_id`	integer ou null	Equipe que assume a conversa

cURL — atendente

curl -X POST "https://app.evoluachat.com.br/api/conversations/456/assign" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id": 5}'

cURL — equipe

curl -X POST "https://app.evoluachat.com.br/api/conversations/456/assign" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"team_id": 2}'

cURL — tirar a atribuição

curl -X POST "https://app.evoluachat.com.br/api/conversations/456/assign" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id": null, "team_id": null}'

Resposta 200

JSON

{
  "success": true,
  "conversation": {
    "id": 456,
    "assignee_id": 5,
    "assignee_name": "Maria Atendente",
    "team_id": 2,
    "team_name": "Suporte Técnico",
    "status": "open"
  }
}

Erros

Código	Mensagem	O que fazer
`400`	assignee_id ou team_id é obrigatório	Envie ao menos um dos dois
`400`	Atendente não encontrado	Confira o ID em /api/users
`400`	Equipe não encontrada	Confira o ID em /api/teams
`404`	Conversa não encontrada	Confira o ID da conversa

Enviar template no WhatsApp Oficial

POST/api/whatsapp-cloud/inboxes/:inbox_id/send-template

Dispara uma mensagem de template aprovado pela Meta. É o caminho para iniciar contato ou retomar conversas fora da janela de 24 horas.

Requer perfil ADMIN. Crie o token com um usuário administrador e use uma inbox do tipo WhatsApp Oficial.

Campos obrigatórios

Campo	Tipo	Descrição
`to`	string	Telefone do destinatário. Máscaras são removidas: `+55 (11) 99999-9999` vira `5511999999999`
`template_name`	string	Nome do template cadastrado na Meta
`language`	string	Idioma do template, como `pt_BR`, `pt_PT` ou `en_US`

Variáveis do template

Há duas formas de preencher os campos entre chaves do template. A primeira é a recomendada.

Campo	Tipo	Descrição
`body_params`	string[]	Valores do corpo, na ordem `{{1}}`, `{{2}}`, ...
`header_params`	string[]	Valores do cabeçalho, na mesma lógica de ordem
`variables`	object	Alternativa com chaves `var_1`, `var_2`, ... ordenadas pelo número

A quantidade de variáveis é conferida antes do envio. Se faltar algum valor, a resposta é 400 indicando quantas variáveis o template espera.

cURL — variáveis no corpo

curl -X POST "https://app.evoluachat.com.br/api/whatsapp-cloud/inboxes/12/send-template" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "template_name": "boas_vindas2",
    "language": "pt_BR",
    "body_params": ["João", "Evolua Chat", "123"]
  }'

cURL — formato var_1, var_2

curl -X POST "https://app.evoluachat.com.br/api/whatsapp-cloud/inboxes/12/send-template" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+55 (11) 99999-9999",
    "template_name": "boas_vindas2",
    "language": "pt_BR",
    "variables": {
      "var_1": "João",
      "var_2": "Evolua Chat",
      "var_3": "123"
    }
  }'

cURL — cabeçalho e corpo

curl -X POST "https://app.evoluachat.com.br/api/whatsapp-cloud/inboxes/12/send-template" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "template_name": "confirmacao_agendamento",
    "language": "pt_BR",
    "header_params": ["Evolua Chat"],
    "body_params": ["João", "15/01", "14:30"]
  }'

Resposta 200

JSON

{
  "ok": true,
  "message_id": "wamid.HBgL..."
}

Erros

Código	Mensagem	O que fazer
`400`	id inválido	O `inbox_id` precisa ser numérico
`400`	to é obrigatório	Informe o telefone com DDI e DDD
`400`	template_name e language são obrigatórios	Preencha os dois campos
`400`	Template requer X variável(eis)	Complete os valores de `body_params` ou `header_params`
`401`	Unauthorized	Token ausente ou inválido
`403`	Forbidden	O usuário do token precisa ser ADMIN
`404`	Inbox não encontrada	A inbox não existe, não é sua ou não é WhatsApp Oficial
`500`	Erro ao enviar template	Falha na comunicação com a Meta — tente novamente

Listar etiquetas

GET/api/labels

Retorna todas as etiquetas da conta, com nome e cor.

cURL

curl -X GET "https://app.evoluachat.com.br/api/labels" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

[
  {
    "id": 1,
    "name": "VIP",
    "color": "#ff0000",
    "created_at": "2026-01-08T10:00:00.000Z"
  },
  {
    "id": 2,
    "name": "Novo Cliente",
    "color": "#00ff00",
    "created_at": "2026-01-08T10:00:00.000Z"
  }
]

Criar etiqueta

POST/api/labels

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da etiqueta
`color`	string	Não	Cor em hexadecimal (padrão `#3498db`)

cURL

curl -X POST "https://app.evoluachat.com.br/api/labels" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"name": "Urgente", "color": "#e74c3c"}'

Resposta 201

JSON

{
  "id": 3,
  "name": "Urgente",
  "color": "#e74c3c",
  "created_at": "2026-01-08T10:00:00.000Z"
}

Atualizar etiqueta

PUT/api/labels/:id

Altera nome, cor ou os dois. Envie apenas o que quiser mudar.

cURL

curl -X PUT "https://app.evoluachat.com.br/api/labels/3" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"name": "Super Urgente", "color": "#c0392b"}'

Resposta 200

JSON

{
  "id": 3,
  "name": "Super Urgente",
  "color": "#c0392b",
  "created_at": "2026-01-08T10:00:00.000Z"
}

Se o ID não existir, a resposta é 404 Etiqueta não encontrada.

Excluir etiqueta

DELETE/api/labels/:id

Apaga a etiqueta e a remove de todos os contatos que a tinham.

cURL

curl -X DELETE "https://app.evoluachat.com.br/api/labels/3" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "ok": true,
  "deleted": {
    "id": 3,
    "name": "Super Urgente",
    "color": "#c0392b",
    "created_at": "2026-01-08T10:00:00.000Z"
  }
}

Listar pipelines

GET/api/kanban/boards

Lista os funis a que o usuário do token tem acesso, com a contagem de etapas e cards.

cURL

curl -X GET "https://app.evoluachat.com.br/api/kanban/boards" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

[
  {
    "id": 1,
    "name": "Vendas",
    "description": "Pipeline de vendas",
    "visibility": "all",
    "team_access": [],
    "managed_by": [],
    "is_archived": false,
    "created_by": 5,
    "created_by_name": "Admin",
    "stages_count": "4",
    "cards_count": "12",
    "created_at": "2025-10-01T14:00:00.000Z",
    "updated_at": "2025-10-15T09:30:00.000Z"
  }
]

Pipeline com etapas e cards

GET/api/kanban/boards/:id

Traz o funil completo: cada etapa com os seus cards, já ordenados por posição.

cURL

curl -X GET "https://app.evoluachat.com.br/api/kanban/boards/1" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "id": 1,
  "name": "Vendas",
  "description": "Pipeline de vendas",
  "visibility": "all",
  "is_archived": false,
  "created_by": 5,
  "created_by_name": "Admin",
  "stages": [
    {
      "id": 10,
      "board_id": 1,
      "name": "Novo",
      "color": "#EAF4FF",
      "position": 0,
      "cards": [
        {
          "id": 100,
          "board_id": 1,
          "stage_id": 10,
          "title": "Lead - Site",
          "description": "Interesse em plano empresarial",
          "contact_id": 42,
          "contact_name": "João Silva",
          "contact_phone_e164": "5511999999999",
          "assigned_to": 5,
          "assigned_to_name": "Carlos",
          "value_amount": "1500.00",
          "priority": "high",
          "tags": ["importante"],
          "position": 0,
          "attachments_count": 2,
          "conversation_id": 300,
          "created_by": 5,
          "created_at": "2025-10-05T12:00:00.000Z"
        }
      ]
    }
  ]
}

Erros

Código	Mensagem	O que fazer
`403`	Sem permissão para acessar este funil	O usuário do token não tem acesso ao pipeline
`404`	Pipeline não encontrado	Confira o ID em /api/kanban/boards

Buscar card por ID

GET/api/kanban/cards/:id

Retorna o card com os dados do contato, do responsável, do pipeline, da etapa atual e da conversa mais recente.

cURL

curl -X GET "https://app.evoluachat.com.br/api/kanban/cards/100" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "id": 100,
  "board_id": 1,
  "board_name": "Vendas",
  "stage_id": 10,
  "stage_name": "Novo",
  "stage_color": "#EAF4FF",
  "title": "Lead - Site",
  "description": "Interesse em plano empresarial",
  "contact_id": 42,
  "contact_name": "João",
  "contact_last_name": "Silva",
  "contact_phone_e164": "5511999999999",
  "contact_email": "joao@email.com",
  "assigned_to": 5,
  "assigned_to_name": "Carlos",
  "value_amount": "1500.00",
  "phone": "11999999999",
  "priority": "high",
  "tags": ["importante", "site"],
  "position": 0,
  "attachments_count": 2,
  "conversation_id": 300,
  "created_by": 5,
  "created_at": "2025-10-05T12:00:00.000Z",
  "updated_at": "2025-10-15T09:30:00.000Z"
}

Campos retornados

Campo	Tipo	Descrição
`board_name`	string	Nome do pipeline
`stage_name`	string	Nome da etapa atual
`stage_color`	string	Cor da etapa em hexadecimal
`contact_id`	number ou null	Contato vinculado ao card
`assigned_to`	number ou null	Usuário responsável
`value_amount`	string ou null	Valor da oportunidade
`priority`	string	`low`, `normal` ou `high`
`tags`	array	Tags do card
`position`	number	Posição dentro da etapa
`attachments_count`	number	Quantidade de anexos
`conversation_id`	number ou null	Conversa mais recente do contato

Criar card

POST/api/kanban/boards/:boardId/cards

Adiciona um card em uma etapa do funil.

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`stage_id`	integer	Sim	Etapa onde o card entra
`title`	string	Sim	Título do card
`contact_id`	integer	Não	Contato vinculado
`description`	string	Não	Descrição
`value_amount`	number	Não	Valor da oportunidade
`phone`	string	Não	Telefone do card
`assigned_to`	integer	Não	Usuário responsável
`priority`	string	Não	`low`, `normal` ou `high`
`tags`	array	Não	Lista de tags

cURL

curl -X POST "https://app.evoluachat.com.br/api/kanban/boards/1/cards" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": 10,
    "title": "Novo lead - Site",
    "contact_id": 42,
    "description": "Interesse em plano empresarial",
    "value_amount": 1500,
    "priority": "high"
  }'

Resposta 201

JSON

{
  "id": 100,
  "board_id": 1,
  "stage_id": 10,
  "title": "Novo lead - Site",
  "position": 0,
  "created_at": "2025-10-05T12:00:00.000Z"
}

A etapa precisa pertencer ao pipeline informado, senão a resposta é 400.

Editar card

PUT/api/kanban/cards/:id

Atualiza um ou mais campos. Envie apenas o que muda; o resto continua como está.

cURL

curl -X PUT "https://app.evoluachat.com.br/api/kanban/cards/100" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lead qualificado",
    "assigned_to": 5,
    "priority": "high"
  }'

Resposta 200

JSON

{
  "id": 100,
  "board_id": 1,
  "stage_id": 10,
  "title": "Lead qualificado",
  "assigned_to": 5,
  "priority": "high"
}

Corpo vazio retorna 400 Nenhum campo para atualizar.

Remover card

DELETE/api/kanban/cards/:id

Exclui o card definitivamente. Não há desfazer.

cURL

curl -X DELETE "https://app.evoluachat.com.br/api/kanban/cards/100" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{ "message": "Card deletado com sucesso" }

Mover card entre pipelines

POST/api/kanban/cards/:id/move

Move o card para outro pipeline e outra etapa. Serve também para avançar etapas dentro do mesmo funil.

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`board_id`	integer	Sim	Pipeline de destino
`stage_id`	integer	Sim	Etapa de destino, dentro desse pipeline

cURL

curl -X POST "https://app.evoluachat.com.br/api/kanban/cards/100/move" \
  -H "Authorization: Bearer tk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "board_id": 2,
    "stage_id": 15
  }'

Resposta 200

JSON

{
  "id": 100,
  "board_id": 2,
  "stage_id": 15
}

Se o card já estiver nesse destino, a resposta continua 200 e traz "message": "Card já está neste pipeline e etapa".

Listar usuários

GET/api/users

Lista os atendentes da conta. Use para descobrir o assignee_id na hora de distribuir conversas ou cards.

cURL

curl -X GET "https://app.evoluachat.com.br/api/users" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

[
  {
    "id": 1,
    "name": "João Admin",
    "nickname": "joao",
    "email": "joao@empresa.com",
    "phone": "11999999999",
    "role": "ADMIN",
    "created_at": "2026-01-08T10:00:00.000Z"
  },
  {
    "id": 2,
    "name": "Maria Atendente",
    "nickname": "maria",
    "email": "maria@empresa.com",
    "phone": "11988888888",
    "role": "AGENT",
    "created_at": "2026-01-08T10:00:00.000Z"
  }
]

O campo role vem como ADMIN ou AGENT.

Buscar usuário por ID

GET/api/users/:id

cURL

curl -X GET "https://app.evoluachat.com.br/api/users/2" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

{
  "id": 2,
  "name": "Maria Atendente",
  "nickname": "maria",
  "email": "maria@empresa.com",
  "phone": "11988888888",
  "role": "AGENT",
  "created_at": "2026-01-08T10:00:00.000Z"
}

Listar inboxes

GET/api/inboxes

Lista as caixas de entrada da conta, tanto as conectadas por QR Code quanto as do WhatsApp Oficial. É daqui que sai o inbox_id usado para abrir conversas e enviar templates.

cURL

curl -X GET "https://app.evoluachat.com.br/api/inboxes" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

[
  {
    "id": 1,
    "name": "WhatsApp Principal",
    "type": "whatsapp",
    "created_at": "2026-01-08T10:00:00.000Z"
  },
  {
    "id": 2,
    "name": "WhatsApp Oficial",
    "type": "whatsapp_cloud",
    "created_at": "2026-01-08T10:00:00.000Z"
  }
]

Tipos de inbox

Tipo	Descrição
`whatsapp`	WhatsApp conectado por QR Code
`whatsapp_cloud`	WhatsApp Oficial (API da Meta)

Buscar inbox por ID

GET/api/inboxes/:id

Traz a inbox com os dados da conexão — útil para monitorar se um número caiu.

cURL

curl -X GET "https://app.evoluachat.com.br/api/inboxes/1" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200 — conexão por QR Code

JSON

{
  "id": 1,
  "name": "WhatsApp Principal",
  "type": "whatsapp",
  "created_at": "2026-01-08T10:00:00.000Z",
  "connection": {
    "id": 1,
    "name": "WhatsApp Principal",
    "phone_number": "+5511999999999",
    "status": "connected",
    "instance_id": "abc123",
    "created_at": "2026-01-08T10:00:00.000Z",
    "updated_at": "2026-01-08T12:00:00.000Z"
  }
}

Resposta 200 — WhatsApp Oficial

JSON

{
  "id": 2,
  "name": "WhatsApp Oficial",
  "type": "whatsapp_cloud",
  "created_at": "2026-01-08T10:00:00.000Z",
  "connection": {
    "id": 1,
    "phone_number_id": "123456789",
    "waba_id": "987654321",
    "display_phone_number": "+5511988888888",
    "verified_name": "Minha Empresa",
    "quality_rating": "GREEN",
    "created_at": "2026-01-08T10:00:00.000Z",
    "updated_at": "2026-01-08T12:00:00.000Z"
  }
}

Campos da conexão

Campo	Onde aparece	Descrição
`status`	QR Code	`connected`, `disconnected` ou `connecting`
`phone_number`	QR Code	Número conectado
`instance_id`	QR Code	Identificador da instância
`phone_number_id`	WhatsApp Oficial	ID do número na Meta
`waba_id`	WhatsApp Oficial	ID da conta WhatsApp Business
`verified_name`	WhatsApp Oficial	Nome verificado da empresa
`quality_rating`	WhatsApp Oficial	Qualidade do número: `GREEN`, `YELLOW` ou `RED`

Listar equipes

GET/api/teams

Retorna as equipes da conta, com os IDs usados para atribuir conversas.

cURL

curl -X GET "https://app.evoluachat.com.br/api/teams" \
  -H "Authorization: Bearer tk_seu_token_aqui"

Resposta 200

JSON

[
  {
    "id": 1,
    "name": "Suporte Técnico",
    "description": "Equipe de suporte",
    "created_at": "2026-01-08T10:00:00.000Z"
  },
  {
    "id": 2,
    "name": "Vendas",
    "description": "Equipe comercial",
    "created_at": "2026-01-08T10:00:00.000Z"
  }
]

Códigos de status

Código	Significado	Descrição
`200`	OK	Requisição concluída
`201`	Created	Registro criado
`400`	Bad Request	Parâmetros inválidos ou faltando
`401`	Unauthorized	Token ausente, expirado ou inválido
`403`	Forbidden	Token válido, mas sem permissão para o recurso
`404`	Not Found	Registro não encontrado
`409`	Conflict	A operação conflita com o estado atual do registro
`429`	Too Many Requests	Limite de requisições atingido
`500`	Internal Server Error	Erro no servidor

Limite de requisições

A API limita a quantidade de chamadas por minuto para manter o sistema estável para todos.

Plano	Limite
Free	60 requisições por minuto
Pro	300 requisições por minuto

Ao ultrapassar o limite, a resposta é 429 Too Many Requests. Em disparos grandes, distribua as chamadas ao longo do tempo e repita a requisição alguns segundos depois quando receber esse código.

Erros comuns

Situação	Causa provável	Como resolver
`401` em todas as chamadas	Cabeçalho errado ou token expirado	Confira se o valor começa com `Bearer` e gere um token novo se preciso
`403` em um endpoint específico	O usuário do token não tem o perfil exigido	Gere o token com um usuário ADMIN
Mensagem não chega no WhatsApp Oficial	Janela de 24 horas fechada	Consulte a janela da conversa e envie um template
Contatos duplicados	Cadastro criado sem consultar antes	Busque por número antes de criar
Conversa abre na inbox errada	`inbox_id` incorreto	Liste as inboxes e confirme o ID
Telefone não encontrado	Número sem DDI	Envie sempre no padrão `+55DDNNNNNNNNN`

Precisa de um endpoint que não está aqui? Fale com o suporte do Evolua Chat com o caso de uso e o volume esperado.