Agente de build
Claude Code, Cursor, Copilot
Escreve a integração no seu app. Precisa de contrato previsível, docs em markdown e OpenAPI. A Shiftz entrega compat Evolution + /openapi.json: ele acerta os nomes de campo sem chutar.
WhatsApp API para IA
Sua IA já sabe usar esta API.
A Shiftz fala o padrão Evolution API v2, o mesmo que os modelos de código viram milhares de vezes no treino. O agente integra trocando a base URL e opera o WhatsApp pelo servidor MCP (Model Context Protocol). Você não ensina a WhatsApp API pra IA; ela já conhece.
Dois agentes
"Agente de IA" são dois bichos diferentes. A Shiftz serve os dois.
Tem o agente que constrói a integração e o que opera o WhatsApp ao vivo. Eles precisam de coisas diferentes. Tratar como se fosse um só é onde a maioria das APIs trava.
Agente de runtime
o agente do seu cliente, em produção
Manda e lê mensagem ao vivo. Precisa de MCP, webhooks confiáveis e erro acionável. A Shiftz entrega servidor MCP nativo, webhooks assinados e eventos de ACK pra ele saber se a mensagem chegou.
Como a IA usa
Os três jeitos de uma IA usar a Shiftz.
Lê
documentação em markdown
Sua IA puxa a doc em texto puro (sem renderizar JS) e te ajuda a construir. Tem /llms.txt e /llms-full.txt prontos pra ingestão.
Escreve
compat Evolution + OpenAPI
O modelo já conhece o padrão Evolution. Some o /openapi.json como contrato de máquina e o código sai certo de primeira.
Opera
servidor MCP
Conecte o agente ao MCP e ele manda mensagem, cria instância e lê status em linguagem natural, com a mesma apikey e o mesmo escopo da API.
Integração trivial
Você aponta. A IA escreve.
Pede pro seu assistente de código: "integra a Shiftz, que é compatível com a Evolution API v2". Passa três linhas de contexto e ele monta o fluxo inteiro: criar instância, conectar, esperar ficar open, enviar.
contexto pro agente
Estou integrando a Shiftz, uma WhatsApp API compatível com Evolution API v2.- Base URL: https://api.shiftz.com.br/v2- Auth: header `apikey: shz_xxx.yyy`- Contrato (OpenAPI): https://api.shiftz.com.br/openapi.jsonImplemente: criar instância → conectar (QR) → esperar "open" → enviar texto.Integre em 5 minutos
O fluxo mínimo: o que o seu agente vai gerar.
bash
# 1. Cria a instância (já pede 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 }' # 2. Conecta e pega o QR (escaneie no celular)curl https://api.shiftz.com.br/v2/instance/connect/meu-bot \ -H "apikey: shz_xxx.yyy" # 3. Espera o estado virar "open"curl https://api.shiftz.com.br/v2/instance/connectionState/meu-bot \ -H "apikey: shz_xxx.yyy" # 4. Manda a primeira mensagemcurl -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!" }'O único passo manual é escanear o QR: o WhatsApp exige o celular. O resto seu agente faz sozinho.
MCP nativo
Conecte seu agente. Ele opera o WhatsApp falando.
Um comando liga a Shiftz ao Claude Code, Claude Desktop, Claude.ai ou Cursor:
bash
claude mcp add -s user --transport http shiftz \ https://api.shiftz.com.br/mcp \ --header "Authorization: Bearer shz_xxx.yyy"Aí é linguagem natural: "cria a instância marketing-01 e me dá o QR", "manda 'Olá' pro 5511999998888", "lista minhas instâncias e o estado de cada uma". A apikey define o escopo: uma chave org-wide vê tudo; uma escopada vê só a instância dela.
As tools shiftz_* cobrem a API inteira: instâncias, mensagens, grupos, perfil, contatos, webhooks e chaves. É function calling sobre o Model Context Protocol, com a mesma apikey e o mesmo escopo da REST.
Sem surpresa em produção
As regras que todo agente precisa saber.
Mande só com a instância open.
Enviar em connecting/qr-code retorna 409. Cheque o connectionState ou espere o evento connection.update.
Valide o número antes.
Número fora do WhatsApp retorna 422. Confere com whatsappNumbers e economiza retry.
Erros são JSON com HTTP semântico.
{ error, details } + status (401, 402, 404, 409, 422, 501, 503). Dá pra tratar de forma determinística.
Webhooks assinados.
Valide o header X-Webhook-Signature: sha256=<hmac> e você sabe que o evento veio mesmo da Shiftz.
Perguntas frequentes
- Minha IA realmente acerta de primeira?
- Na prática, sim, porque o padrão Evolution v2 já está no treino dos modelos de código. Apontar o agente pro /openapi.json fecha o resto: ele acerta nomes de campo e formatos sem inventar.
- Preciso saber programar pra usar?
- Pra integrar via API ou MCP, alguém do seu time precisa configurar a chave e o webhook. Depois disso, o agente opera sozinho em linguagem natural pelo MCP.
- Qual a diferença entre usar a API e usar o MCP?
- API é pra construir a integração no seu app (build). MCP é pra um agente operar o WhatsApp em runtime, sem você escrever as chamadas. Muita gente usa os dois.
- Funciona com Claude, GPT e outros modelos?
- A compatibilidade Evolution ajuda qualquer modelo de código a escrever a integração. O servidor MCP segue o Model Context Protocol: funciona com qualquer cliente que fale MCP (Claude Code, Claude Desktop, Cursor e afins).
- Como meu agente sabe se a mensagem chegou?
- Pelo evento de ACK (MESSAGES_UPDATE): sent → delivered → read → played. Você recebe isso no webhook assinado.
- E o QR Code, dá pra automatizar?
- O QR em si precisa de uma pessoa escaneando no celular: é exigência do WhatsApp. Tudo em volta é automatizável: gerar o QR (raw ou base64), receber qrcode.updated e detectar o open.
Dá uma apikey pro seu agente e sai do caminho.
Dá uma apikey pro seu agente e deixa ele integrar no build e operar no runtime. Trial de 7 dias, sem cartão.