Guia de integração

Evolution API com o Mensageiro

O bot OpenAI da Evolution API responde cada conversa da instância. Com duas mudanças, ele responde com qualquer modelo do Mensageiro.

1. Aponte o servidor para o Mensageiro

A credencial OpenAI da Evolution API guarda só um nome e uma chave. Não existe campo de URL base. O serviço cria o cliente com new OpenAI({ apiKey }), e esse cliente lê a URL base da variável de ambiente OPENAI_BASE_URL. Defina a variável no servidor da Evolution API e reinicie o container:

bash
1# .env da Evolution API (ou environment: do docker-compose)
2OPENAI_BASE_URL=https://api.uplinkswitch.com/v1

A variável vale para todas as instâncias desse servidor. Cada instância continua com a própria credencial.

2. Cadastre a credencial

Use a chave Mensageiro no campo apiKey. O bot e as configurações padrão apontam para essa credencial pelo id, em openaiCredsId.

http
1POST {{baseUrl}}/openai/creds/{{instance}}
2
3{
4 "name": "mensageiro",
5 "apiKey": "SUA_CHAVE_MENSAGEIRO"
6}

3. Crie o bot

Use botType igual a chatCompletion e escreva em model um id da página de preços. O tipo assistant usa a Assistants API da OpenAI, que o Mensageiro não atende.

http
1POST {{baseUrl}}/openai/create/{{instance}}
2
3{
4 "enabled": true,
5 "openaiCredsId": "ID_DA_CREDENCIAL",
6 "botType": "chatCompletion",
7 "model": "claude-sonnet-5-5",
8 "systemMessages": [
9 "Você atende clientes da Loja Exemplo pelo WhatsApp. Responda em português, em até três frases."
10 ],
11 "assistantMessages": [],
12 "userMessages": [],
13 "maxTokens": 300,
14 "triggerType": "all",
15 "triggerOperator": "none",
16 "triggerValue": "",
17 "expire": 20,
18 "keywordFinish": "#SAIR",
19 "delayMessage": 1000,
20 "unknownMessage": "Não entendi. Pode repetir?",
21 "listeningFromMe": false,
22 "stopBotFromMe": true,
23 "keepOpen": false,
24 "debounceTime": 10,
25 "ignoreJids": []
26}
  • triggerType: all responde toda mensagem; keyword responde quando triggerValue bate com o triggerOperator (contains, equals, startsWith, endsWith, regex).
  • stopBotFromMe: com true, o bot para quando um atendente humano escreve pelo mesmo número.
  • debounceTime: segundos para juntar mensagens seguidas do cliente numa só pergunta.
  • keywordFinish: a palavra que encerra a sessão do bot.

4. Configurações padrão

Deixe speechToText em false com uma chave Mensageiro. A transcrição de áudio da Evolution API chama o endereço da OpenAI direto, com o modelo whisper-1, e não passa pela URL base.

http
1POST {{baseUrl}}/openai/settings/{{instance}}
2
3{
4 "openaiCredsId": "ID_DA_CREDENCIAL",
5 "expire": 20,
6 "keywordFinish": "#SAIR",
7 "delayMessage": 1000,
8 "unknownMessage": "Não entendi. Pode repetir?",
9 "listeningFromMe": false,
10 "stopBotFromMe": true,
11 "keepOpen": false,
12 "debounceTime": 10,
13 "ignoreJids": [],
14 "speechToText": false
15}

5. Controle o gasto

Crie uma chave por instância ou por cliente e defina o limite mensal no console. No limite, a API responde 402 com monthly_limit_reached e só aquele bot para. Para pausar um contato, use POST {{baseUrl}}/openai/changeStatus/{{instance}} com status igual a paused.