Uma superfície versionada
As rotas REST públicas vivem em /v1. Rotas compatíveis em /api/v1 chegam na mesma API.
referência v1 em produção
Referência da API InstantReply
Construa sobre a REST API de produção para conversas de WhatsApp, Instagram e Messenger. Aqui você encontra auth, paginação, mensagens, jornadas, templates, webhooks assinados, debug de entregas e endpoints para desenvolvedores.
O que um desenvolvedor pode construir
Use o InstantReply como camada de mensagens do seu produto ou ferramenta interna. Seu backend pode ler conversas, enviar respostas, atualizar contatos, rotear leads, disparar jornadas de WhatsApp, validar templates e reagir a mensagens de clientes em tempo real.
Serve para operação real
É a mesma superfície de produção usada pelo dashboard, automações, respostas IA e envios de jornada.
Sem polling
Registre um endpoint webhook e receba POSTs assinados quando o cliente responde ou a entrega muda.
Autenticação, paginação e erros
Autentique com uma API key com escopo em Authorization: Bearer $IR_API_KEY. Separe keys live e test. Você pode rotacionar keys no developer settings sem trocar o segredo de assinatura do webhook.
curl https://api.instantreply.co/v1/conversations \
-H "Authorization: Bearer $IR_API_KEY"curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \
-H "Authorization: Bearer $IR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content":"Thanks for reaching out - how can we help?"}'Paginação por cursor
Todo endpoint de lista aceita ?cursor= e retorna o próximo cursor quando existem mais registros. Trate o cursor como opaco e envie de volta exatamente como recebeu.
Erros previsíveis
Falhas retornam um envelope JSON com code, message, doc_url e request_id. Guarde X-Request-Id quando precisar que o suporte rastreie uma chamada.
Grupos de endpoints em produção
Estas são as rotas mais usadas por desenvolvedores. O inventário completo está no catálogo REST, mas esta página explica para que serve cada grupo e como ele entra na integração.
Conversas e mensagens
Leia conversas, envie respostas e sincronize histórico de mensagens.
- GET
/v1/conversationsLista conversas com filtros por status, canal, responsável e paginação por cursor.
- GET
/v1/conversations/:idLê uma conversa com cliente, canal, etapa, tags e atividade recente.
- PATCH
/v1/conversations/:idAtualiza atribuição, status, tags ou campos de roteamento da conversa.
- GET
/v1/conversations/:id/messagesLê o histórico de mensagens de uma conversa.
- POST
/v1/conversations/:id/messagesEnvia uma resposta pelo canal da conversa com o escopo messages:send. Exige Idempotency-Key. integration_id precisa corresponder à conta conectada à conversa; caso contrário, retorna 409 ACCOUNT_MISMATCH.
- GET
/v1/messagesLista mensagens de todas as conversas para auditoria, sync ou analítica.
- POST
/v1/messagesEnvia conteúdo de 1 a 4096 caracteres com o escopo messages:send e Idempotency-Key obrigatória. Use conversation_id ou contact_id mais channel para uma conversa existente. integration_id seleciona a conta conectada (consulte GET /v1/channels); chats de contato ambíguos retornam 409 ACCOUNT_REQUIRED.
- GET
/v1/messages/:idBusca detalhes de conteúdo e entrega de uma mensagem.
Contatos, canais e analítica
Mantenha o registro do cliente sincronizado e consulte métricas operacionais.
- GET
/v1/contactsLista contatos com etapa, score, owner e identidade de canal.
- GET
/v1/contacts/:idLê um perfil de contato e contexto de conversa.
- PATCH
/v1/contacts/:idAtualiza campos criados por lead capture ou CRM.
- GET
/v1/channelsLista canais conectados de WhatsApp, Instagram e Messenger.
- PATCH
/v1/channels/:integration_idAtiva respostas de DM com { ai_enabled } ou respostas a comentários dessa página com { ai_comment_replies_enabled }; exige automations:write.
- GET
/v1/analytics/summaryConsulta métricas de volume, resposta e conversão.
- GET
/v1/usageLê uso de plano para mensagens, IA, webhooks e chamadas API.
- GET
/v1/statusEstado público sem autenticação das dependências de banco de dados e Redis: 200 quando saudáveis, 503 quando degradadas; error_rate fica null até haver histórico real suficiente.
Keys e webhooks
Gerencie API keys e assine eventos em tempo real no seu servidor.
- GET
/v1/keysLista API keys ativas e escopos.
- POST
/v1/keysCria uma key com escopo para backend, agente ou ambiente test.
- POST
/v1/keys/:id/rotateRotaciona uma key sem downtime.
- DELETE
/v1/keys/:idRevoga uma key imediatamente.
- GET
/v1/webhooksLista endpoints webhook.
- POST
/v1/webhooksRegistra um endpoint webhook assinado.
- DELETE
/v1/webhooks/:idDesativa um endpoint webhook.
- GET
/v1/webhooks/:id/deliveriesInspeciona tentativas recentes e falhas.
Jornadas, triggers e campanhas
Dispare jornadas de WhatsApp, revise entregas e sincronize eventos de negócio.
- GET
/v1/journeysLista journey templates disponíveis na conta.
- POST
/v1/triggerInscreve um contato numa jornada ou template workflow.
- GET
/v1/trigger/status/:idExplica o resultado atual de entrega de um trigger.
- POST
/v1/trigger/validateValida um payload antes do envio.
- POST
/v1/trigger/batchDispara um lote de contatos com resultado por linha.
- POST
/v1/eventsEnvia um evento externo de negócio para o InstantReply.
- POST
/v1/campaigns/:id/sendInicia o envio de uma campanha aprovada.
Templates e ferramentas developer
Valide, envie e depure templates de WhatsApp sem adivinhar política da Meta.
- GET
/v1/templatesLista templates e status no InstantReply e na Meta.
- POST
/v1/templates/:id/sendEnvia um template aprovado com templates:send. integration_id seleciona o remetente; se omitido, usa o número vinculado ao template ou o único número ativo. Se houver vários números sem seleção, retorna 409 AMBIGUOUS_INTEGRATION.
- POST
/v1/templatesCria um rascunho de template.
- POST
/v1/templates/:id/validateRevisa categoria e oferece coaching para UTILITY.
- POST
/v1/templates/:id/submitEnvia o template para revisão da Meta.
- GET
/v1/developer/capabilitiesLê escopos, features habilitadas e limites.
- GET
/v1/developer/onboardingConsulta checklist de integração.
- GET
/v1/developer/limitsConsulta rate limits e cotas.
- GET
/v1/developer/troubleshooting/errors/:codeBusca um erro conhecido do provedor.
Webhooks e seguranca
Registre POST /v1/webhooks uma vez e o InstantReply enviará eventos em tempo real para seu servidor. A entrega é at-least-once, então processe X-InstantReply-Delivery de forma idempotente.
1. Crie um endpoint HTTPS
Seu servidor precisa aceitar POST JSON e responder 2xx em ate 8 segundos.
2. Registre o endpoint
Chame POST /v1/webhooks com uma key que tenha webhooks:write e assine eventos exatos, *, ou wildcards como message.*.
3. Guarde o segredo
O segredo whsec_ aparece uma unica vez. Verifique cada entrega e use GET /v1/webhooks/:id/deliveries para debugar falhas.
Verificação de assinatura
Ao registrar um webhook, seu segredo de assinatura whsec_ é exibido uma única vez, apenas no corpo dessa resposta: guarde-o imediatamente, ele nunca é mostrado de novo. Perdeu? Exclua o endpoint e registre um novo. Verifique X-InstantReply-Signature com HMAC-SHA256 sobre timestamp.rawBody antes de confiar no payload. Tentativas recentes ficam em GET /v1/webhooks/:id/deliveries.
app.post("/webhooks/instantreply", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.header("X-InstantReply-Timestamp")
const signature = req.header("X-InstantReply-Signature")
const rawBody = req.body.toString("utf8")
const signedPayload = timestamp + "." + rawBody
verifyHmacSha256(process.env.IR_WEBHOOK_SECRET, signedPayload, signature)
res.sendStatus(204)
})| Evento | Quando dispara |
|---|---|
message.received | Um cliente envia mensagem por WhatsApp, Instagram ou Messenger. |
message.sent | Sai uma mensagem pela IA, dashboard, API, automação ou jornada. |
conversation.created | Uma conversa nova abre por inbound, coexistence ou jornada. |
conversation.closed | Uma conversa é resolvida manualmente ou por automação. |
conversation.assigned | O owner muda por atribuição manual ou regra de roteamento. |
contact.updated | Lead extraction ou CRM sync atualiza um contato. |
contact.opted_out | Um contato cancela o recebimento, por exemplo ao responder STOP, para o seu CRM suprimi-lo. |
contact.opted_in | Um contato que tinha cancelado volta a aceitar mensagens, por exemplo ao responder START. |
template.status_update | A Meta reporta revisão ou mudança de qualidade de um template. |
message.delivery_failed | O provedor rejeita ou falha a entrega depois das tentativas. |
ticket.created | Um ticket de suporte é criado a partir de um repasse ou de uma revisão. |
ticket.updated | O status, a prioridade ou a atribuição de um ticket muda. |
ticket.assigned | O responsável pelo ticket muda. |
ticket.closed | Um ticket de suporte é resolvido. |
Ciclo de templates e debug de entregas
Os endpoints de templates ajudam equipes a publicar templates de WhatsApp com compliance. Valide categoria, envie para a Meta, inspecione resultados do provedor e explique erros conhecidos.
- POST /v1/templates/:id/validate revisa categoria e dá coaching para UTILITY.
- POST /v1/templates/:id/submit envia o template para revisão da Meta.
- GET /v1/trigger/status/:id explica resultados de entrega para triggers.
- GET /v1/developer/onboarding e /limits mostram setup, features, cotas e rate limits.
OpenAPI gerado em produção
Swagger/OpenAPI gerado está disponível em ambientes não produtivos para validação interna. Produção não expõe /openapi.json de forma intencional. Use esta referência, o catálogo REST e o guia rápido como superfície pública.
Checklist de produção
Sua integração está pronta quando estes pontos estão certos.
Use https://api.instantreply.co/v1 em produção.
Guarde API keys live e test separadamente.
Verifique X-InstantReply-Signature antes de aceitar um webhook.
Trate duplicados com X-InstantReply-Delivery.
Reenvie POST somente com estratégia de idempotência.
Respeite janelas de mensagem do canal e opt-outs.