Conversations

List Conversation Threads

GET /api/v1/conversations

Scope: conversations:read

Returns conversation threads with AI-generated summaries, sentiment, and interest level.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Results per page (1-100)

Response

{
  "data": [
    {
      "id": "d4e5f6a7-...",
      "organization_id": "org-uuid-...",
      "lead_id": "a1b2c3d4-...",
      "status": "active",
      "ai_summary": "Lead interested in roof replacement. Scheduling estimate for next week.",
      "sentiment": "positive",
      "interest_level": "high",
      "requires_human": false,
      "created_at": "2026-05-08T10:00:00Z",
      "updated_at": "2026-05-10T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 15,
    "total_pages": 1
  }
}

Get Messages for a Lead

GET /api/v1/conversations/:leadId

Scope: conversations:read

Returns the message history for a specific lead, sorted chronologically (oldest first).

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Messages per page (1-100)

Example

curl "https://api.brightlyai.app/api/v1/conversations/a1b2c3d4-..." \
  -H "Authorization: Bearer brk_your_key"

Response

{
  "data": [
    {
      "id": "msg-uuid-1",
      "type": "sms",
      "direction": "outbound",
      "body": "Hi Jane! This is Sarah from Smith Roofing. We got your request for a roof inspection. When works best for you this week?",
      "status": "delivered",
      "sent_at": "2026-05-08T10:00:00Z",
      "created_at": "2026-05-08T10:00:00Z"
    },
    {
      "id": "msg-uuid-2",
      "type": "sms",
      "direction": "inbound",
      "body": "Thursday afternoon would be great!",
      "status": "received",
      "sent_at": "2026-05-08T10:05:00Z",
      "created_at": "2026-05-08T10:05:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 8,
    "total_pages": 1
  }
}

Send Message

POST /api/v1/conversations/:leadId/messages

Scope: messages:write

Sends an SMS message to a lead. The message is compliance-checked before sending.

Request Body

Field	Type	Required	Description
`body`	string	Yes	Message text (1-1600 chars)

Example

curl -X POST "https://api.brightlyai.app/api/v1/conversations/a1b2c3d4-.../messages" \
  -H "Authorization: Bearer brk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "Hi Jane, confirming your appointment tomorrow at 10am!"}'

Response

{
  "data": {
    "sent": true,
    "lead_id": "a1b2c3d4-..."
  }
}

Compliance Blocking

If the lead has opted out of SMS or is on the Do Not Call list, the API returns 422:

{
  "error": {
    "code": "compliance_blocked",
    "message": "Message blocked: lead has opted out of SMS",
    "retryable": false
  }
}