Guia de conexão

Conectar a Evolution API

Com uma instância da Evolution API conectada ao WhatsApp, o agente responde por ela. Você informa três dados no console e o Mensageiro configura o webhook da instância.

Antes de começar, crie o agente em Agentes, no console. A instância conectada aqui passa a ser atendida por ele.

1. Confira a instância

A instância precisa estar conectada ao WhatsApp, pelo QR code no Manager ou por GET /instance/connect/{instance}. O estado deve ser open:

http

1GET https://evolution.suaempresa.com.br/instance/connectionState/loja

2apikey: API_KEY_DA_INSTANCIA

2. Junte os três dados

Campo no Mensageiro	O que é
`instance_url`	O endereço do seu servidor da Evolution API, sem barra no fim e sem caminho: `https://evolution.suaempresa.com.br`.
`instance_name`	O nome da instância, como aparece no Manager: `loja`.
`api_key`	A chave que vai no cabeçalho `apikey`. A Evolution aceita o token da instância ou a chave global (`AUTHENTICATION_API_KEY`). Prefira o token da instância: ele abre só essa instância.

3. Conecte o canal no Mensageiro

No console, abra o agente e conecte um canal do tipo Evolution API com instance_url, instance_name e api_key. Pela API, é a mesma chamada:

bash

1curl https://api.mensageiro.ai/v1/agents/ID_DO_AGENTE/channels \

2 -H "Authorization: Bearer sk-msg-SUA_CHAVE" \

3 -H "Content-Type: application/json" \

4 -d '{

5 "kind": "evolution",

6 "instance_url": "https://evolution.suaempresa.com.br",

7 "instance_name": "loja",

8 "api_key": "API_KEY_DA_INSTANCIA"

9 }'

Na hora de criar o canal, o Mensageiro chama POST {instance_url}/webhook/set/{instance} e aponta o webhook da instância para o canal. A API key fica selada e nunca volta numa resposta.

json

1{

2 "data": {

3 "id": "ch_…",

4 "kind": "evolution",

5 "status": "active",

6 "label": "loja",

7 "webhook_url": "https://api.mensageiro.ai/api/channels/evo/ch_…?s=…",

8 "verify_token": null,

9 "webhook_set": true,

10 "last_error": null

11 }

12}

Com webhook_set igual a true, terminou: vá para o passo 5.

4. Se webhook_set vier false

O Mensageiro não conseguiu configurar a instância (a URL não respondeu ou a chave não tem acesso). Configure você mesmo com o webhook_url do canal, inteiro, com o parâmetro ?s=. No Manager, abra os webhooks da instância, cole a URL, ative o evento MESSAGES_UPSERT e deixe o webhook por eventos e o base64 desligados. Pela API:

http

1POST https://evolution.suaempresa.com.br/webhook/set/loja

2apikey: API_KEY_DA_INSTANCIA

3Content-Type: application/json

5{

6 "webhook": {

7 "enabled": true,

8 "url": "WEBHOOK_URL_DO_CANAL",

9 "byEvents": false,

10 "base64": false,

11 "events": ["MESSAGES_UPSERT"]

12 }

13}

Na Evolution API v2, os campos ficam dentro de "webhook", como o schema do servidor exige. byEvents desligado importa: ligado, a Evolution soma o nome do evento ao fim da URL e o endereço do canal deixa de valer. Confira o resultado:

http

1GET https://evolution.suaempresa.com.br/webhook/find/loja

2apikey: API_KEY_DA_INSTANCIA

5. Teste

Mande uma mensagem de outro celular para o número da instância. O evento MESSAGES_UPSERT chega ao Mensageiro, o agente responde pela própria instância (POST /message/sendText/{instance}) e a conversa aparece no console.

Quando o cliente escreve atendente, o agente pausa por 12 horas para aquele contato. Como o celular continua conectado à instância, a sua equipe responde pelo próprio WhatsApp.

Se algo não funcionar

Sinal	O que conferir
`webhook_set` igual a `false`	A `instance_url` precisa responder pela internet e a `api_key` precisa abrir a instância. Ou siga o passo 4.
Nenhuma mensagem chega	Estado da instância `open`, evento `MESSAGES_UPSERT` ativo e `byEvents` desligado em `/webhook/find`.
O canal fica com `status` `error`	Leia `last_error` no canal e confira o estado da instância e a `api_key`.
Áudio ou imagem sem resposta	O agente responde texto e pede ao cliente para escrever. Grupos e status ficam de fora.

Para responder com o bot OpenAI da própria Evolution, sem agente hospedado, veja o guia do bot OpenAI da Evolution. Para o número oficial da Meta, veja Conectar WhatsApp oficial.