# eCommunicate Conversations API

# Overview
The eCommunicate Conversations API enables you to create, manage, and send messages within
**long-lived WhatsApp conversation sessions**. Unlike standard WhatsApp messaging, where a
business-initiated session automatically expires after 24 hours, eCommunicate Conversations
remain open **until explicitly closed** by either the business or the recipient, allowing
ongoing dialogue that can span days, weeks, or even months.

## What are Conversations?
A conversation is a persistent, bi-directional communication channel between a WhatsApp
Business number and a customer. These conversations are **not** governed by the
[WhatsApp 24-hour session window](https://developers.facebook.com/docs/whatsapp/pricing)
that applies to standard notification and session messages.

Conversations are ideal for use cases where an extended dialogue is required, such as:
- **Sales and lead nurturing** — a salesperson opens a conversation with a prospect and
  follows up over several weeks until a deal is closed.
- **Customer onboarding** — guide a customer through multi-step onboarding processes at
  their own pace.
- **After-sales support** — keep a support thread open for the duration of a service case
  or warranty claim.
- **Appointment management** — maintain an open channel for scheduling, rescheduling, and
  confirming appointments.

Each conversation is assigned a unique `conversationId` (UUID) upon creation. This identifier
is used across all subsequent API calls to send messages, check status, and close the session.

## Authentication
Every request requires a Developer API Key in the `Authorization` header. This key authenticates
your application and associates requests with your eCommunicate account. Contact the eCommunicate
team to obtain your key, along with approved template IDs and template names.

## How It Works
1. **Create** a conversation between your WhatsApp Business number and a recipient using the
   [Create a conversation](#tag/Manage-Conversations/operation/createConversation) endpoint.
   You will receive a `conversationId` to reference in all future operations.
2. **Send** text, media, call-to-action, card, or quick-reply messages within the conversation
   using the [Send a conversation message](#tag/Send-Messages/operation/sendConversationMessage)
   endpoint. All messages are delivered through pre-approved WhatsApp templates.
3. **Monitor** the conversation at any time: check the
   [remaining time](#tag/Manage-Conversations/operation/getRemainingTime) before expiry, or
   [list all conversations](#tag/Manage-Conversations/operation/getMyConversations) to review
   their status.
4. **Close** the conversation when the interaction is complete using the
   [Close a conversation](#tag/Manage-Conversations/operation/closeConversation) endpoint.
   Once closed, no further messages can be sent within that session.

## Message Types
The API supports five template-based message types, each suited to different communication needs:

| Type | Description |
|---|---|
| Text Only | A template populated with body text parameters only. Use for simple informational messages. |
| Text + Media | A template combining body text with a media attachment such as a PDF, image, or video. Ideal for sending invoices, brochures, or product images. |
| Call to Action | A template with body text and one or more CTA buttons (e.g., "Visit Website" or "Call Now"). Use to drive specific customer actions. |
| Card | A rich template combining media, body text, and recipient tracking. Suited for product showcases or interactive catalogues. |
| Quick Reply | A template with body text and interactive quick-reply buttons that can control conversation flow (start or end a conversation branch). Use for guided decision trees or surveys. |


Version: 2.1.0
License: Apache 2.0

## Servers

Live — WhatsApp Cloud Server URL
```
https://api.payless4messaging.com
```

Live — WhatsApp Lite Server URL
```
https://api.payless4messages.com
```

## Security

### apikeyAuth

Developer API key provided by eCommunicate.

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[eCommunicate Conversations API](https://docs.ecommunicate.co.za/_bundle/apis/conversations.yaml)

## Manage Conversations

### Session Control
Create, close, and monitor the lifecycle of long-lived WhatsApp conversations. Use these
endpoints to open a new conversation between your WhatsApp Business number and a customer,
check remaining session time, retrieve a paginated list of all your conversations, or
permanently close a conversation when the interaction is complete.


### Create a conversation

 - [POST /payless4messaging-service/WhatsApp/WhatsAppConversations/createWhatsAppConversation](https://docs.ecommunicate.co.za/apis/conversations/manage-conversations/createconversation.md): Opens a new long-lived conversation session between your WhatsApp Business number and a
customer. Unlike standard 24-hour WhatsApp sessions, this conversation remains active
until it is explicitly closed by either party.

On success, the response includes a conversationId (UUID) that uniquely identifies the
session. You must pass this identifier to all subsequent API calls to send messages,
check remaining time, or close the conversation. Store the conversationId securely
on your side for future reference.

### Close a conversation

 - [GET /payless4messaging-service/WhatsApp/WhatsAppConversations/closeWhatsAppConversation](https://docs.ecommunicate.co.za/apis/conversations/manage-conversations/closeconversation.md): Permanently closes an active long-lived conversation. Once a conversation is closed, no
further messages can be sent or received within it. This action is irreversible; to resume
communication with the same recipient, you must create a new conversation using the
Create a conversation endpoint.

Use this endpoint when the business interaction is complete, for example after a sale has
been finalized, a support case has been resolved, or the customer has opted out.

### Get remaining conversation time

 - [GET /payless4messaging-service/WhatsApp/WhatsAppConversations/getRemainingTime](https://docs.ecommunicate.co.za/apis/conversations/manage-conversations/getremainingtime.md): Returns the remaining time, in seconds, before the specified conversation session expires.
Although eCommunicate conversations are long-lived, they do have an upper time limit.
Use this endpoint to proactively monitor session health, display countdown timers in your
application, or trigger automated renewal or closure workflows before the session lapses.

### List all conversations (paginated)

 - [GET /payless4messaging-service/WhatsApp/WhatsAppConversations/getAllWhatsAppConversationsForCurrentUser](https://docs.ecommunicate.co.za/apis/conversations/manage-conversations/getmyconversations.md): Retrieves a paginated list of all conversations belonging to the authenticated user.
Use the page and size query parameters to control pagination, and the optional
searchString parameter to filter results by sender number, recipient number, or
conversation ID.

This endpoint is useful for building conversation management dashboards, displaying
active and closed sessions, or performing bulk operations across your conversation
inventory.

### List conversations by client reference

 - [GET /payless4messaging-service/WhatsApp/WhatsAppConversations/getAllWhatsAppConversationsByClientRef](https://docs.ecommunicate.co.za/apis/conversations/manage-conversations/getconversationsbyclientref.md): Retrieves all conversations associated with a specific client reference identifier.
The clientRef is a label assigned to conversations during creation that groups them
under a common business entity, project, or campaign.

Use this endpoint when you need to retrieve every conversation tied to a particular
client or organizational unit, regardless of conversation state. The response is a
flat array of conversation objects (not paginated).

## Send Messages

### Conversation Messaging
Send structured template-based messages within active long-lived conversation sessions. This
includes text-only messages, media attachments (PDFs, images, videos), call-to-action buttons,
rich cards, and quick-reply interactive components. All messages are delivered through
pre-approved WhatsApp templates and are associated with an existing `conversationId`.


### Send a conversation message

 - [POST /whatsapp-api-service/v2/json](https://docs.ecommunicate.co.za/apis/conversations/send-messages/sendconversationmessage.md): Sends a message to one or more recipients within a long-lived conversation session. The
message is delivered asynchronously; a 202 Accepted response confirms that the request
has been queued for processing. The request body shape is selected by messageType:

CONVERSATION — free-text message (see ConversationTextRequest)

A plain-text message delivered into an already-active conversation. Identify the
conversation with messages[].conversationId and put the body on each
messages[].messageText. A free-text message carries no template —
templateName/templateId, components, and conversationParameters do not apply.
- sender — Your registered WhatsApp Business number.
- messages[].conversationId — The active conversation to deliver into (from the create-conversation call).
- messages[].messageText — The plain-text body.
- messages[].recipients or messages[].recipientNumbers — The list of recipients.

NOTIFICATION — template message (see NotificationMessageRequest)

A template-based message. Specify an approved WhatsApp template and the variable
substitutions that populate its dynamic fields. A notification does not take a
conversationId.
- templateName / templateId — The pre-approved WhatsApp template to render (the
  snake_case forms template_name / template_id are also accepted).
- messages[].components — An array of template variable substitutions. Use type: "body"
  for text placeholders and type: "button" for button parameters.
- messages[].media — An optional media attachment (PDF, image, video) identified by a
  publicly accessible URL.
- messages[].recipients or messages[].recipientNumbers — The list of recipients.
  Use recipientNumbers when you need extended tracking via gstId.

Quick Reply buttons (NOTIFICATION only):
Use the button component with conversationParameters to define interactive quick-reply
buttons that control conversation flow. Each button can be assigned a conversationState
of start (to begin a conversation branch) or end (to terminate it), enabling guided
decision trees and survey-style interactions.

## Analytics

### Delivery Insights
Retrieve aggregated delivery and engagement metrics for conversation-type messages over a
specified date range. Analytics include counts for messages submitted, sent, delivered, read,
and failed, giving you full visibility into conversation performance and recipient engagement.


### Get conversation analytics

 - [GET /payless4messaging-service/WhatsApp/WhatsAppAnalytics/getConversationAnalyticsForCurrentLoginUser](https://docs.ecommunicate.co.za/apis/conversations/analytics/getconversationanalytics.md): Retrieves aggregated delivery and engagement statistics for conversation-type messages
over a specified date range. The response provides counts for messages submitted, sent,
delivered, read, and failed, giving you a complete picture of conversation performance.

Use this endpoint to power reporting dashboards, monitor delivery health, and identify
engagement trends across your conversation messaging activity.