External APIGet Livechat Conversations API

Get Conversations API

This endpoint retrieves a list of conversations with filtering and pagination options.

Endpoint

GET https://client-api.wappcloud.com/api/v1/external/conversations

Authentication

  • x-api-key (required): Your API key for authentication.
  • Authorization (required): Bearer token in the format: 
    Authorization: Bearer <your_token>
ParameterTypeRequiredDescription
pagestringNoPage number for pagination (default: 1)
limitstringNoNumber of items per page (default: 10)
message_directionstringNoFilter by message direction: incoming or outgoing
contact_namestringNoFilter by contact name
contact_numberstringNoFilter by contact number

Example:

Get Live Chat Conversations 
GET /external/conversations?page=1&limit=10&message_direction=incoming
x-api-key: your_api_key_here
Authorization: Bearer your_token_here

Success Response (200 OK)

{
    "chats": [
        {
            "_id": "6501a1c2f1e4b2001a9b1234",
            "convoId": "65019f9ef1e4b2001a9b5678",
            "contactId": "65019f9ef1e4b2001a9b9999",
            "contactName": "Rahul Sharma",
            "contactNumber": 9876541230,
            "message_direction": "incoming",
            "message_body": "Hello, is the order ready?",
            "message_type": "text",
            "media_url": null,
            "createdAt": "2025-08-25T10:15:30.000Z",
            "updatedAt": "2025-09-01T08:20:10.000Z"
        },
        {
            "_id": "6501a1c2f1e4b2001a9b1235",
            "convoId": "65019f9ef1e4b2001a9b5678",
            "contactId": "65019f9ef1e4b2001a9b9999",
            "contactName": "Rahul Sharma",
            "contactNumber": 9876541230,
            "message_direction": "outgoing",
            "message_body": "Yes, your order has been packed and will be delivered today.",
            "message_type": "text",
            "media_url": null,
            "createdAt": "2025-08-25T10:16:00.000Z",
            "updatedAt": "2025-09-01T08:20:10.000Z"
        },
        {
            "_id": "6501a1c2f1e4b2001a9b1236",
            "convoId": "65019f9ef1e4b2001a9b5678",
            "contactId": "65019f9ef1e4b2001a9b9999",
            "contactName": "Rahul Sharma",
            "contactNumber": 9876541230,
            "message_direction": "incoming",
            "message_body": "Thank you! 😊",
            "message_type": "text",
            "media_url": null,
            "createdAt": "2025-08-25T10:17:10.000Z",
            "updatedAt": "2025-09-01T08:20:10.000Z"
        },
        {
            "_id": "6501a1c2f1e4b2001a9b1237",
            "convoId": "65019f9ef1e4b2001a9b5678",
            "contactId": "65019f9ef1e4b2001a9b9999",
            "contactName": "Rahul Sharma",
            "contactNumber": 9876541230,
            "message_direction": "outgoing",
            "message_body": "You're welcome! Have a great day ahead.",
            "message_type": "text",
            "media_url": null,
            "createdAt": "2025-08-25T10:17:40.000Z",
            "updatedAt": "2025-09-01T08:20:10.000Z"
        }
    ],
    "totalCount": 4,
    "totalPages": 1,
    "currentPage": 1,
    "nextPage": null,
    "prevPage": null
}

Response Fields

Root Object

  • chats (array): List of conversations
  • totalCount (integer): Total number of conversations matching filters
  • totalPages (integer): Total number of pages available
  • currentPage (integer): Current page number
  • nextPage (integer/null): Next page number, null if none
  • prevPage (integer/null): Previous page number, null if none

Conversation Object

  • _id (string): Conversation ID
  • convoId (string): Same as _id, represents the conversation identifier
  • contactId (string): Unique contact identifier
  • contactName (string): Name of the contact
  • contactNumber (number): Contact’s phone number
  • message_direction (string): Direction of the message (incoming or outgoing)
  • message_body (string): Content of the message
  • message_type (string): Type of message (text, file, etc.)
  • media_url (string): URL of the media file (if any)
  • createdAt (string): ISO 8601 timestamp when message was created
  • updatedAt (string): ISO 8601 timestamp when message was last updated

Error Responses

401 Unauthorized

{
  "code": 401,
  "message": "Missing or invalid API key or token",
  "success": false
}

400 Bad Request

{
  "code": 400,
  "message": "Invalid query parameters",
  "success": false
}

Notes

  • All date filters are inclusive
  • Pagination defaults: page=1, limit=10
  • Conversations are sorted by updatedAt (latest first)
Get API RequestSend Direct Message