API da XBASE: visão geral
O que a API da XBASE faz, o endereço base, como autenticar e a lista de endpoints de WhatsApp, Instagram, webhooks e agentes externos.
Atualizado em
A API da XBASE deixa outro sistema usar o seu workspace: enviar templates de WhatsApp, responder comentários e DMs do Instagram, receber eventos por webhook e revisar as respostas de um agente externo.
Cada chamada usa uma chave de API do workspace, com só as permissões que você escolher.
Endereço base
Todas as rotas ficam em:
https://api.xbase.app/api/external/v1O corpo das requisições e das respostas é JSON (Content-Type: application/json). Datas vêm em ISO 8601, em UTC.
Autenticação
Mande a chave no cabeçalho Authorization de toda requisição:
Authorization: Bearer xsk_...A chave começa com xsk_, vale só no workspace em que foi criada e só para os escopos marcados nela. Veja como criar em Autenticação.
Endpoints
| Método e rota | Escopo | O que faz |
|---|---|---|
GET /me | qualquer | Workspace e escopos da chave |
GET /whatsapp/numbers | whatsapp:send | Números de WhatsApp do workspace |
GET /whatsapp/templates | whatsapp:send | Templates com o id para envio |
POST /whatsapp/templates | whatsapp:send | Envia um template de WhatsApp |
GET /instagram/accounts | instagram:read | Contas do Instagram conectadas |
POST /instagram/comments/{commentId}/reply | instagram:act | Responde um comentário em público |
POST /instagram/comments/{commentId}/private-reply | instagram:act | Responde o autor do comentário por DM |
POST /instagram/comments/{commentId}/hide | instagram:act | Oculta ou mostra um comentário |
POST /instagram/messages | instagram:act | Envia uma DM |
GET /webhook · PUT /webhook · DELETE /webhook | webhooks:manage | Consulta, cadastra ou desliga o webhook da chave |
POST /agents/{agentId}/output-review | guardrails:review | Revisa a resposta de um agente externo |
Escopos
Ao criar a chave, você marca as permissões. Cada uma é um escopo:
| Escopo | Na tela | Libera |
|---|---|---|
whatsapp:send | Enviar templates de WhatsApp | listar números e templates e enviar templates |
instagram:read | Ler contas do Instagram | listar as contas conectadas |
instagram:act | Responder, ocultar e mandar DM no Instagram | responder e ocultar comentários e mandar DM |
webhooks:manage | Receber eventos (comentários e DMs) por webhook | cadastrar e desligar o webhook |
guardrails:review | Revisar respostas do agente (guardrails) | revisar a resposta de um agente externo |
Rota chamada sem o escopo responde 403 MISSING_SCOPE.
Regras e limites
- Tudo fica preso ao workspace da chave. Número, conta, agente ou conversa de outro workspace responde 404, como se não existisse.
- A chave não é uma pessoa. Ela não entra na XBASE pela tela e não usa as permissões de quem a criou: vale só o que os escopos liberam.
- Os limites da Meta e da Gupshup continuam valendo. Por exemplo, a DM do Instagram só sai dentro da janela de 24 horas e o WhatsApp só aceita templates aprovados.
- Os erros têm um
codeestável, que a sua integração deve tratar no lugar do texto da mensagem: Erros.
Perguntas frequentes
Veja também
Prospecção de leads no Google Maps
Como a XBASE encontra empresas no Google Maps por tema e cidade, separa quem tem celular, exporta a lista e manda os leads para o funil.
Autenticação: chaves de API
Como criar uma chave de API da XBASE, escolher os escopos, mandar a chave nas requisições, conferir com GET /me e revogar.