Como conectar o WhatsApp a um agente de IA em 5 minutos

Para conectar um agente de IA ao WhatsApp em poucos minutos, você cria uma instância na Shiftz, conecta o número escaneando um QR Code e passa a enviar mensagens pela API REST ou pelo servidor MCP. Como a Shiftz é compatível com a Evolution API v2 — o padrão que os modelos de código já viram no treino —, o próprio agente escreve a integração trocando só a base URL.

Este guia mostra o fluxo mínimo do zero ao primeiro "Olá", e onde a coisa costuma travar.

O que você precisa antes de começar

• Uma conta na Shiftz (o trial é de 7 dias, sem cartão).
• Sua API key no formato shz_<prefixo>.<segredo>, pega no painel.
• Um celular com WhatsApp pra escanear o QR uma vez.

Passo 1 — Crie a instância

Uma chamada cria a conexão e já devolve o QR:

curl -X POST https://api.shiftz.com.br/v2/instance/create \
  -H "apikey: shz_xxx.yyy" -H "Content-Type: application/json" \
  -d '{ "instanceName": "meu-bot", "qrcode": true }'

Passo 2 — Conecte o número

Peça o QR e escaneie no WhatsApp do celular (Aparelhos conectados → Conectar aparelho):

curl https://api.shiftz.com.br/v2/instance/connect/meu-bot \
  -H "apikey: shz_xxx.yyy"

Passo 3 — Espere o estado virar open

Só mande mensagem quando a instância estiver conectada:

curl https://api.shiftz.com.br/v2/instance/connectionState/meu-bot \
  -H "apikey: shz_xxx.yyy"

Passo 4 — Envie a primeira mensagem

curl -X POST https://api.shiftz.com.br/v2/message/sendText/meu-bot \
  -H "apikey: shz_xxx.yyy" -H "Content-Type: application/json" \
  -d '{ "number": "5511999998888", "text": "Olá do meu agente!" }'

Deixe o agente operar por MCP

Se você quer que um agente opere o WhatsApp em linguagem natural (em vez de você escrever as chamadas), conecte o servidor MCP:

claude mcp add -s user --transport http shiftz \
  https://api.shiftz.com.br/mcp \
  --header "Authorization: Bearer shz_xxx.yyy"

Depois disso, o agente entende pedidos como "cria a instância suporte-01 e me dá o QR" ou "manda 'Olá' pro 5511999998888".

O que costuma quebrar

• Enviar com a instância fora do open. Mandar em connecting ou qr-code retorna 409. Cheque o connectionState ou espere o evento connection.update.
• Número fora do WhatsApp. Retorna 422. Valide antes com o endpoint de checagem de números.
• QR não automatizável. O escaneamento precisa de uma pessoa no celular — é exigência do WhatsApp. Todo o resto é automatizável.

Próximo passo

Crie sua conta grátis e rode esse fluxo hoje — leva alguns minutos e não pede cartão.