API pública v1 — organização, campanhas e mensagens

Visão geral

A API pública /api/v1 destina-se a integradores (ex.: n8n). Inclui campanhas (disparo em massa) e mensagens (texto em conversa/contato já existente).

• Autenticação: header Authorization: Bearer <chave> onde a chave é criada em Configurações da organização → Chaves de API (plano Professional).
• Identificadores: campanhas, templates e integrações usam UUID público. Conversas usam conversation_id numérico (o número que identifica a conversa no painel).
• OpenAPI: especificação em GET /api/v1/openapi. No painel logado: API (menu) ou Configurações → Chaves de API → documentação interativa.
• Compliance: listas, consentimento e base legal ficam no CRM/automação do cliente; o OSBChat fornece o canal técnico de envio.

Documentação relacionada

• Campanhas no painel — assistente de nova campanha, agendar, cancelar e ver o envio na conversa (usuários do painel).

Idempotência

Nos POST de criar campanha, destinatários, init e enviar mensagem, envie opcionalmente o header Idempotency-Key. Requisições repetidas com a mesma chave devolvem a mesma resposta gravada (quando já processada).

Endpoints

integration_uuids / integration_uuid são os UUID públicos das integrações (mesmo valor exibido na tela da integração).

Enviar mensagem (POST /api/v1/messages)

Envia somente texto para um destinatário que já existe no canal. Não cria contato nem conversa nova. A entrega é assíncrona (fila outbound); a resposta HTTP confirma o enfileiramento.

Corpo:

• Com conversation_id: a conversa deve pertencer à organização da chave e à integration_uuid informada.
• Com external_user_id: o contato já deve existir nesse canal e ter uma conversa já existente para esse contato + integração.

Resposta 200: { "message_id", "conversation_id", "queued": true }.

WhatsApp: texto livre fora da janela de 24h da Meta pode falhar no provedor (igual ao reply do painel). Para outreach frio, use campanhas com template aprovado.

curl -sS -X POST "$BASE/api/v1/messages" \
  -H "Authorization: Bearer $OSBC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-demo-001" \
  -d "{\"integration_uuid\":\"$INT_UUID\",\"conversation_id\":12345,\"content\":\"Olá! Continuando nosso atendimento.\"}"

Agendamento (campanhas)

Campanhas com des_status = scheduled e tis_scheduled no futuro passam a enviar automaticamente na data/hora indicada. Acompanhe o estado pelo GET da campanha ou pela lista no painel.

Canal e-mail

Integrações do tipo e-mail ainda não estão disponíveis para disparo em massa por esta API. Use canais como WhatsApp ou Telegram enquanto o suporte a e-mail de campanha não estiver liberado.

Exemplo n8n — campanha (curl)

Substitua BASE, OSBC_KEY, INT_UUID e, se houver, TMPL_UUID.

curl -sS -X GET "$BASE/api/v1/campaigns/ping" \
  -H "Authorization: Bearer $OSBC_KEY"

curl -sS -X POST "$BASE/api/v1/campaigns" \
  -H "Authorization: Bearer $OSBC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-demo-001" \
  -d "{\"des_name\":\"Demo API\",\"integration_uuids\":[\"$INT_UUID\"],\"message_template_uuid\":\"$TMPL_UUID\"}"

Resposta inclui campaign_uuid. Em seguida:

curl -sS -X POST "$BASE/api/v1/campaigns/$CAMP_UUID/recipients" \
  -H "Authorization: Bearer $OSBC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recipients-demo-001" \
  -d "{\"recipients\":[{\"des_phone\":\"5511999999999\",\"des_name\":\"Teste\",\"des_variables\":{\"nome\":\"Teste\"}}]}"

curl -sS -X POST "$BASE/api/v1/campaigns/$CAMP_UUID/init" \
  -H "Authorization: Bearer $OSBC_KEY" \
  -H "Idempotency-Key: init-demo-001"

Erros comuns

• 401 Unauthorized: Bearer ausente, chave revogada/expirada ou plano abaixo de Professional.
• 404: UUID de campanha, integração, template, conversa ou contato/canal não pertence à organização da chave (ou conversa inexistente para o external_user_id).
• 400: corpo inválido, operação em campanha que não está em rascunho, ou conversation_id incompatível com a integração.

Boas práticas

• Use Idempotency-Key em automações que possam repetir o mesmo passo.
• Para campanhas, faça poll do status após init em vez de assumir entrega no mesmo request.
• Para mensagens avulsas, confirme no painel que o envio saiu; a API só garante que a mensagem entrou na fila de envio.
• Enforce listas e consentimento no CRM antes de campanhas.