Live Chat

The Live Chat system enables agent-based customer conversations with ticket tracking, team assignment, and message history across WhatsApp, Web, and Facebook channels.

The Live Chat system is built around three core concepts:

Customer Message ──> Unassigned Queue ──> Agent Picks Up ──> Active Chat
                                                                  │
                                                    ┌─────────────┼─────────────┐
                                                    ▼             ▼             ▼
                                                 Resolved    Transferred     Closed
                                                  (Ticket)   (to team)    (Rating widget)

Follow this three-step flow to receive an incoming WhatsApp message and retrieve the full conversation history.

Incoming Message ──> Webhook fires ──> Look up ChatParticipant ──> Get messages
    (customer)       (your server)      (by sender number)        (by participant ID)

When a customer sends a message, your configured incomingMessageURL receives a POST with the message payload. See Webhooks — Incoming message payload for full details.

{
  "profileName": "John Smith",
  "sender": "+27987654321",
  "senderUserId": "ZA.1021033720668862",
  "username": "john_smith",
  "receiver": "+27123456789",
  "text": "Hi, I need help with my order",
  "messageType": "INTERACTION",
  "messageContentType": "TEXT",
  "gstId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "participantId": "participant-uuid",
  "sentTime": "2026-01-15T10:30:00.000+00:00",
  "status": "RECEIVED"
}

Use the sender field without a + to look up the chat participant in Step 2. When the phone number is withheld, match on userId (the customer BSUID) instead — it is present on the chat participant even when the number is not.

List your chats and filter by the sender's phone number to find the latest conversation. The v2 list endpoint selects which conversations to return with a scope filter — the agent and client are resolved from your API key, so you only choose the tab:

GET /pl4chat-service/api/v2/chats?scope=my

Use the search parameter with the sender's phone number or BSUID (senderUserId) to narrow results directly, or filter client-side after fetching. The response is a page of ChatParticipantResponse objects. Match on phoneNumber or userId — a customer with a withheld phone number is identified only by userId (BSUID).

curl -X GET \
  "https://api.payless4messaging.com/pl4chat-service/api/v2/chats?scope=unassigned&page=0&size=50&search=27987654321" \
  -H "Authorization: $ECOMM_API_KEY"

Use the participant ID from step 2 to retrieve the full message history:

curl -X GET \
  "https://api.payless4messaging.com/pl4chat-service/api/v2/messages?participantId=participant-uuid" \
  -H "Authorization: $ECOMM_API_KEY"

If you have the GSTN (Global System Tracking Number) or CTN (Customer Tracking Number) from the chat participant object, you can retrieve messages directly without needing the participant ID:

GET /pl4chat-service/api/v2/messages/tracking/{trackingNumber}

curl -X GET \
  "https://api.payless4messaging.com/pl4chat-service/api/v2/messages/tracking/a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890" \
  -H "Authorization: $ECOMM_API_KEY"

After retrieving messages, mark the conversation as read — this clears the unread badge and sends a read receipt to the customer in one call:

POST /pl4chat-service/api/v2/messages/read?participantId=cp-a1b2c3d4

Each chat participant carries:

Close or reopen a conversation with its id — the acting agent is resolved from your API key, so there's no request body to assemble:

POST /pl4chat-service/api/v2/chats/{id}/terminate   # close (sends the rating widget if configured)
POST /pl4chat-service/api/v2/chats/{id}/open        # reopen and assign to you

Both return the updated ChatParticipantResponse.

One endpoint sends on every channel. Set channel (WHATSAPP, WEB, or FACEBOOK) and text — the agent is resolved from your API key:

POST /pl4chat-service/api/v2/messages

{
  "participantId": "participant-uuid",
  "channel": "WHATSAPP",
  "tempId": "unique-temp-uuid",
  "text": "Here is the information you requested."
}

tempId is optional — supply a client-generated string only if you want it echoed back to reconcile an optimistic UI message; otherwise omit it. The response is the stored MessageResponse (with your tempId echoed back when you sent one). To quote/reply to an earlier message, also set quotedExternalMessageId.

Upload the file, then send the returned mediaUrl — the same flow works for any channel:

POST /pl4chat-service/api/v2/messages/media   # multipart/form-data, field "file" -> { mediaUrl, mediaType }
POST /pl4chat-service/api/v2/messages         # { participantId, channel, mediaUrl, text? }

The content type defaults to MEDIA when a mediaUrl is present, so you don't need to set it.

POST /pl4chat-service/api/v2/messages/typing?participantId=participant-uuid

Shows a typing bubble to the customer while the agent is composing a reply.

POST /pl4chat-service/api/v2/messages/read?participantId=participant-uuid

GET /pl4chat-service/ticket/search

Required parameters:

Optional filters:

PUT /pl4chat-service/ticket/{ticketId}/status?newStatus=RESOLVED

Available statuses:

GET /pl4chat-service/ticket/by-ticket-number?ticketNumber=TCK-001

Manage customer contact records linked to your account.

PUT /payless4messaging-service/WhatsApp/contacts/{id}

{
  "fullName": "Jane Smith"
}