Conversations API

Manage WhatsApp Business conversations programmatically. List active customer chats, assign agents, close resolved threads, and filter by status for your support workflows.

---

List conversations

Retrieve a paginated list of conversations for your organization.

GET /api/whatsapp/conversations

Query parameters:

Parameter	Type	Default	Description
page	number	1	Page number for pagination
limit	number	20	Results per page (max: 100)
status	string	—	Filter: open, closed, ai_handling, escalated
assignee	string	—	Filter by assigned user ID (UUID)

Response:

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "contactId": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
        "contact": {
          "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
          "name": "Ahmed Hassan",
          "phone": "+971501234567",
          "avatar": null
        },
        "status": "open",
        "assigneeId": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx",
        "channel": "whatsapp",
        "lastMessage": {
          "text": "When will my order arrive?",
          "timestamp": "2026-05-16T14:22:00.000Z",
          "direction": "inbound"
        },
        "unreadCount": 2,
        "aiHandling": false,
        "createdAt": "2026-05-15T09:00:00.000Z",
        "updatedAt": "2026-05-16T14:22:00.000Z"
      },
      {
        "id": "conv_b2c3d4e5-6789-01ab-cdef-2345678901ab",
        "contactId": "contact_e2d3c4b5-6789-01ab-cdef-bcdefabcdefg",
        "contact": {
          "id": "contact_e2d3c4b5-6789-01ab-cdef-bcdefabcdefg",
          "name": "Sarah Johnson",
          "phone": "+14155557890",
          "avatar": "https://cdn.example.com/avatars/sarah.jpg"
        },
        "status": "ai_handling",
        "assigneeId": null,
        "channel": "whatsapp",
        "lastMessage": {
          "text": "Thanks for the information!",
          "timestamp": "2026-05-16T13:45:00.000Z",
          "direction": "inbound"
        },
        "unreadCount": 0,
        "aiHandling": true,
        "createdAt": "2026-05-16T13:30:00.000Z",
        "updatedAt": "2026-05-16T13:45:00.000Z"
      }
    ],
    "total": 156,
    "page": 1,
    "limit": 20,
    "hasNext": true
  }
}

Conversation statuses:

Status	Description
open	Active conversation awaiting response
ai_handling	AI agent is handling the conversation
escalated	Escalated from AI to a human agent
closed	Conversation resolved and closed

---

Get conversation

Retrieve a single conversation by ID, including full contact details.

GET /api/whatsapp/conversations/:conversationId

Response:

{
  "success": true,
  "data": {
    "id": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "contactId": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
    "contact": {
      "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
      "name": "Ahmed Hassan",
      "phone": "+971501234567",
      "email": "ahmed@example.com",
      "labels": ["vip", "returning"],
      "avatar": null
    },
    "status": "open",
    "assigneeId": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx",
    "assignee": {
      "id": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx",
      "name": "Support Agent",
      "email": "agent@yourcompany.com"
    },
    "channel": "whatsapp",
    "lastMessage": {
      "text": "When will my order arrive?",
      "timestamp": "2026-05-16T14:22:00.000Z",
      "direction": "inbound"
    },
    "unreadCount": 2,
    "aiHandling": false,
    "metadata": {
      "source": "organic",
      "firstMessageAt": "2026-05-15T09:00:00.000Z"
    },
    "createdAt": "2026-05-15T09:00:00.000Z",
    "updatedAt": "2026-05-16T14:22:00.000Z"
  }
}

Error (404):

{
  "success": false,
  "error": "Conversation not found"
}

---

Close conversation

Mark a conversation as resolved. This stops AI handling and removes it from the active queue.

POST /api/whatsapp/conversations/:conversationId/close

Request body: (empty or optional)

{
  "resolution": "resolved"
}

Response:

{
  "success": true,
  "data": {
    "id": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "status": "closed",
    "closedAt": "2026-05-16T15:00:00.000Z",
    "closedBy": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx"
  }
}

---

Assign conversation

Assign a conversation to a team member. This transfers ownership and sends a notification to the assigned user.

POST /api/whatsapp/conversations/:conversationId/assign

Request body:

{
  "userId": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx"
}

Response:

{
  "success": true,
  "data": {
    "id": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "assigneeId": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx",
    "assignee": {
      "id": "user_12345678-abcd-efgh-ijkl-mnopqrstuvwx",
      "name": "Support Agent",
      "email": "agent@yourcompany.com"
    },
    "status": "open",
    "updatedAt": "2026-05-16T15:05:00.000Z"
  }
}

Error — user not in organization (403):

{
  "success": false,
  "error": "User is not a member of this organization"
}

---

Error responses

Status Code	Error	Description
400	"Invalid conversation ID"	Malformed UUID
401	"Unauthorized"	Missing or invalid auth headers
403	"Forbidden"	User doesn't have access to this conversation
404	"Conversation not found"	ID does not exist in your organization
429	"Rate limit exceeded"	Too many requests — retry after cooldown
500	"Internal server error"	Unexpected failure