Interactions API

Interações registram o histórico de atividades de um lead: ligações, emails, reuniões, notas e eventos do sistema.

GET/api/v1/integration/leads/:identifier/interactionsinteractions:read

Listar interações 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)
`type`	string	Filtrar por tipo (NOTE, CALL, etc)

Bash

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

Resposta

JSON

{
  "success": true,
  "data": {
    "interactions": [
      {
        "id": "int_001",
        "type": "CALL",
        "title": "Ligação de follow-up",
        "description": "Cliente interessado, agendou reunião",
        "metadata": { "duration": 480 },
        "createdAt": "2024-01-15T10:30:00.000Z",
        "createdBy": { "id": "usr_001", "name": "João" }
      },
      {
        "id": "int_002",
        "type": "STATUS_CHANGE",
        "title": "Status alterado",
        "description": "open → in_progress",
        "isInternal": true,
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 2 }
  }
}

POST/api/v1/integration/leads/:identifier/interactionsinteractions:write

Adicionar interação ao lead

Body Parameters

Campo	Tipo	Descricao
`type`obrigatório	enum	Tipo da interação Ex: `CALL`
`title`	string	Título da interação
`description`	string	Descrição detalhada
`metadata`	object	Dados extras (duração, resultado, etc)
`isInternal`	boolean	Se true, não visível para integradores

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads/clx123abc456/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MEETING",
    "title": "Reunião de demonstração",
    "description": "Demonstração do produto para equipe de vendas",
    "metadata": {
      "duration": 3600,
      "platform": "zoom",
      "participants": ["maria@cliente.com", "jose@cliente.com"]
    }
  }'

Tipos de Interação

Tipos permitidos via API

Tipo	Descrição	Ícone
`NOTE`	Nota ou observação	📝
`CALL`	Ligação realizada/recebida	📞
`EMAIL`	Email enviado/recebido	📧
`MEETING`	Reunião agendada/realizada	📅
`COMMENT`	Comentário interno	💬
`TASK_CREATED`	Tarefa criada	📋
`TASK_COMPLETED`	Tarefa concluída	✅
`CUSTOM`	Tipo personalizado	🔧

Tipos gerados pelo sistema

Estes tipos são criados automaticamente pelo sistema e não podem ser criados via API:

STATUS_CHANGEPRIORITY_CHANGETAG_ADDEDTAG_REMOVEDASSIGNEDUNASSIGNEDCREATEDUPDATEDCONVERTEDCLOSED

Campos de Metadata

O campo metadata aceita qualquer estrutura JSON. Sugerimos usar estes campos conforme o tipo:

Tipo	Campos sugeridos
`CALL`	duration (segundos), result, phoneNumber
`EMAIL`	subject, from, to, messageId
`MEETING`	duration, platform, participants, link
`CUSTOM`	Qualquer estrutura de sua preferência

Próximos Passos

Conversations API

Gerenciar conversas e mensagens

Leads API

CRUD completo de leads