Conversations API

Gerencie conversas e mensagens de leads. Ideal para integração com chatbots, WhatsApp Business, sistemas de atendimento e CRMs.

GET/api/v1/integration/conversationsconversations:read

Listar conversas de um lead

Query Parameters

Campo	Tipo	Descricao
`page`	number	Página atual (default: 1)
`limit`	number	Itens por página (default: 20, max: 100)
`channel`	string	Filtrar por canal (WHATSAPP, EMAIL, etc)
`status`	string	Filtrar por status (open, closed)

Bash

curl "https://dev-api-tools.helbioads.com/api/v1/integration/leads/clx123abc456/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta

JSON

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "conv_001",
        "externalId": "whatsapp_5511999999999",
        "channel": "WHATSAPP",
        "status": "open",
        "subject": "Atendimento WhatsApp",
        "messagesCount": 15,
        "lastMessageAt": "2024-01-15T14:30:00.000Z",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1 }
  }
}

GET/api/v1/integration/conversations/:idconversations:read

Buscar conversa com mensagens

Bash

curl "https://dev-api-tools.helbioads.com/api/v1/integration/conversations/conv_001?includeMessages=true&messagesLimit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta

JSON

{
  "success": true,
  "data": {
    "conversation": {
      "id": "conv_001",
      "channel": "WHATSAPP",
      "status": "open",
      "messages": [
        {
          "id": "msg_001",
          "direction": "INBOUND",
          "type": "TEXT",
          "content": "Olá! Gostaria de saber mais sobre o produto",
          "createdAt": "2024-01-15T10:00:00.000Z"
        },
        {
          "id": "msg_002",
          "direction": "OUTBOUND",
          "type": "TEXT",
          "content": "Olá! Claro, vou te explicar...",
          "createdAt": "2024-01-15T10:01:00.000Z"
        }
      ]
    }
  }
}

POST/api/v1/integration/conversationsconversations:write

Criar nova conversa

Body Parameters

Campo	Tipo	Descricao
`channel`obrigatório	enum	Canal da conversa Ex: `WHATSAPP`
`externalId`	string	ID externo para deduplicação
`subject`	string	Assunto/título da conversa
`messages`	array	Mensagens iniciais

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads/clx123abc456/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "WHATSAPP",
    "externalId": "whatsapp_5511988888888",
    "subject": "Atendimento via WhatsApp",
    "messages": [
      {
        "direction": "INBOUND",
        "content": "Olá! Vi o anúncio de vocês e quero saber mais",
        "externalId": "wamid.abc123"
      }
    ]
  }'

POST/api/v1/integration/conversations/:id/messagesconversations:write

Adicionar mensagem à conversa

Body Parameters

Campo	Tipo	Descricao
`direction`obrigatório	enum	INBOUND (cliente), OUTBOUND (você) Ex: `INBOUND`
`type`	enum	TEXT, IMAGE, AUDIO, VIDEO, FILE, etc Ex: `TEXT`
`content`obrigatório	string	Conteúdo da mensagem
`externalId`	string	ID da mensagem no seu sistema
`metadata`	object	Dados extras: mediaUrl, mimeType, etc

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/conversations/conv_001/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "OUTBOUND",
    "type": "TEXT",
    "content": "Obrigado pelo contato! Vou verificar e retorno em instantes.",
    "externalId": "wamid.xyz789"
  }'

Canais Disponíveis

💬WHATSAPP

📧EMAIL

🗨️CHAT

📞PHONE

📱SMS

👤FACEBOOK

📷INSTAGRAM

✈️TELEGRAM

✏️MANUAL

🔌API

📋OTHER

Tipos de Mensagem

Tipo	Descrição	Metadata sugerido
`TEXT`	Texto simples	-
`IMAGE`	Imagem	mediaUrl, mimeType, caption
`AUDIO`	Áudio/Voz	mediaUrl, mimeType, duration
`VIDEO`	Vídeo	mediaUrl, mimeType, duration
`FILE`	Documento/Arquivo	mediaUrl, mimeType, fileSize, fileName
`LOCATION`	Localização	latitude, longitude, address
`TEMPLATE`	Template HSM (WhatsApp)	templateName, components
`INTERACTIVE`	Botões/Lista	buttons[], sections[]
`SYSTEM`	Mensagem do sistema	-
`NOTE`	Nota interna	-

Exemplo com Mídia

Para mensagens com mídia, use o campo metadata:

JSON

{
  "direction": "INBOUND",
  "type": "IMAGE",
  "content": "Foto do produto",
  "externalId": "wamid.img_001",
  "metadata": {
    "mediaUrl": "https://example.com/image.jpg",
    "mimeType": "image/jpeg",
    "fileSize": 125000,
    "caption": "Esse é o modelo que me interessa"
  }
}

Próximos Passos

Sync API

Criar conversa junto com lead

Webhooks

Receber notificações de mensagens