Documentação / API v1

Construa com o SummuChat.

Entenda como empresas, projetos, canais, agentes e automações se conectam. Use a API para enviar mensagens, receber eventos e integrar seu sistema.

Começar pelo guia Ver autenticação

01 / GUIAPrepare sua operaçãoEmpresa, projeto, canal e chave de API. 02 / APIEnvie mensagensEnvio, autenticação e idempotência. 03 / EVENTOSReceba eventosWebhooks para manter seu sistema em sincronia.

Quickstart

Envie a primeira mensagem e prepare o fluxo para agentes.

Crie uma empresa, um projeto e uma instância no painel. Depois copie a API key do tenant e chame o endpoint pelo seu backend.

Crie a empresa

Empresas isolam projetos, API keys, instâncias, logs e uso.

Conecte o canal

Escaneie o QR Code e mantenha um runtime ativo por número WhatsApp.

Acione a API

Envie mensagens, entregue contexto ao agente e observe eventos por webhook.

curl -X POST https://api.summuchat.com/v1/messages/send \
  -H "x-summuchat-key: SUMMUCHAT_TENANT_API_KEY" \
  -H "Idempotency-Key: docs-first-message-001" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "your-instance-id",
    "to": "+5511999999999",
    "text": "Hello from SummuChat"
  }'

Core concepts

The SummuChat data model.

The platform is organized around tenant isolation. Every resource belongs to a company and should be accessed through scoped credentials.

CompanyBusiness boundary for projects, members, billing and audit logs.

ProjectWorkspace for instances, automations, agents and webhook configuration.

InstanceA connected WhatsApp runtime. One number should have one active socket.

ConversationNormalized message history between an instance and a recipient.

AutomationWebhook or workflow triggered by platform events.

AgentAI or operator workflow that can read context and respond through the platform.

Authentication

Use tenant API keys from your backend.

Public documentation never exposes real keys. Generate, rotate and revoke credentials in the private dashboard.

Header x-summuchat-key: SUMMUCHAT_TENANT_API_KEY

Do not send tenant keys from browsers, mobile apps or public repositories.

Messages

Message endpoints.

Start with text messages. Media, templates and advanced payloads should follow the same tenant and instance boundaries.

MethodPathPurpose

POST/v1/messages/send

Send an outbound message through a connected instance.

WhatsApp oficial

Meta Cloud API com credenciais da empresa.

O provedor oficial usa os ativos Meta da empresa: WABA ID, Phone Number ID, token de acesso, token de verificação e modelos aprovados. Salvar credenciais não troca a instância automaticamente; a ativação é uma ação separada com MFA.

MétodoRotaUso

GET/webhooks/meta/:instanceId

Verifica o webhook da Meta usando hub.verify_token.

POST/webhooks/meta/:instanceId

Recebe mensagens e status de entrega da instância.

POST/v1/messages/send

Envia texto ou modelo conforme o provedor ativo.

{
  "instanceId": "company-main",
  "to": "5531999999999",
  "type": "template",
  "template": {
    "name": "payment_reminder",
    "language": "pt_BR",
    "components": []
  }
}

Credenciais

Tokens ficam criptografados no banco, mascarados no painel e não retornam ao navegador.

Modelos

Sincronize os modelos aprovados da Meta antes de enviar mensagens fora da janela de conversa.

Ativação explícita

O provedor só muda para whatsapp_cloud após validação e ativação no painel.

Safe delivery

Contact health and consent.

SummuChat separates company-declared consent from engagement signals detected automatically.

Declared consent

The company can grant, revoke or block a contact with source, scope and internal evidence.

Automatic signals

Inbound messages, replies, likely opt-out and engagement score update contact health automatically.

Audited actions

Sensitive changes require MFA when enabled and write contact events plus audit logs.

Formal consent remains the responsibility of the company using SummuChat.

Instances

Conecte e monitore canais WhatsApp.

Cada instância representa um runtime WhatsApp dentro de um projeto. Use o painel para conectar por QR Code e a API para consultar status, logs e disponibilidade.

Criação

Crie a instância dentro de um projeto antes de enviar mensagens ou acionar automações.

Runtime

Mantenha uma sessão ativa por número e acompanhe ready, disconnected e QR pendente pelo painel.

Escopo

Sempre valide que a API key pertence ao tenant e ao projeto da instância solicitada.

MethodPathPurpose

GET/v1/instances

List instances available for the authenticated tenant.

GET/v1/instances/:instanceId/status

Consulta status operacional da instância.

Agents API

Agentes operam com contexto e regras do projeto.

Use agentes para atendimento, triagem, vendas ou pós-venda. Eles podem receber contexto, decidir a próxima ação e responder por um canal permitido.

Disponibilidade da API Configure agentes no painel

A API pública de agentes depende de habilitação na sua instalação. Consulte a equipe antes de integrar esses endpoints.

Automations

Automatize etapas sem perder rastreabilidade.

Automações podem reagir a mensagens recebidas, status de entrega, decisões de agentes ou eventos externos do seu produto.

Tipos de execução Use event_driven para automações contínuas, scheduled_once para dia e hora específicos e scheduled_relative para lembretes antes de uma data de referência.

Timezone O cliente/API envia config.timezone em formato IANA. O SummuChat valida o timezone e calcula o disparo no fuso escolhido pela empresa ou usuário.

Painel do projeto Automações criadas pelo painel ou pela API aparecem no projeto com origem API/Painel e execuções previstas quando plannedRuns for informado.

Execuções agendadas Use automation-executions para o SummuChat lembrar, enviar agora, pausar, cancelar, retomar ou reagendar lembretes pela API.

message.received conversation.idle tag.added appointment.created appointment.reminder.due POST /v1/automation-executions PATCH /v1/automation-executions/:sourceEventId DELETE /v1/automation-executions/:sourceEventId

{
  "projectId": "your-project-id",
  "name": "Lembrete de atendimento",
  "provider": "internal",
  "triggerEvent": "appointment.created",
  "config": {
    "origin": "api",
    "source": "crm",
    "executionMode": "scheduled_relative",
    "timezone": "America/Sao_Paulo",
    "plannedRuns": 3,
    "deliveryPlan": {
      "referenceAt": "2030-07-05T18:00:00-03:00",
      "sendNow": true,
      "offsetsMinutesBefore": [60, 30]
    }
  }
}

PATCH /v1/automation-executions/:sourceEventId
{
  "action": "pause",
  "projectId": "your-project-id"
}

scheduled paused canceled processing sent failed

Webhooks

Receba eventos do SummuChat.

Configure webhooks por projeto ou automação. Seu endpoint deve responder rápido, validar token e processar eventos de forma idempotente.

Validação de assinatura Verifique a assinatura HMAC antes de processar o evento

Use os headers de timestamp e assinatura, o corpo exato recebido e o token do destino. Responda com HTTP 2xx após aceitar o evento.

{
  "event": "message",
  "projectId": "project-id",
  "instanceId": "instance-id",
  "message": {
    "id": "message-id",
    "from": "5511999999999",
    "text": "Olá",
    "fromMe": false
  }
}

Realtime

Live updates for dashboards and operations.

Realtime events are designed for private dashboards. Authenticate the user, validate company access on the server and subscribe only to allowed rooms.

new_message message_updated conversation_updated instance_status_changed qr_code_updated agent_status_changed automation_executed webhook_received

Security

Security rules for production integrations.

Keep keys server-side

Tenant keys should never be exposed in client-side code.

Validate tenant access

Never trust companyId or projectId sent only by the frontend.

Use idempotency

Protect message sends, webhooks and billing actions from duplicate processing.

Audit changes

Record who created keys, changed webhooks, connected instances or edited automations.

Errors

Common response format.

{
  "ok": false,
  "error": "instance not found"
}