Enqueue Communications API Documentation

Overview

The EnqueueCommunications API allows clients to send messages by enqueuing communications with recipient details and content. This endpoint is primarily used for scheduling messages to be processed and delivered by the system.

Endpoint

URL: https://api.wiraya.com/api/EnqueueCommunications
Method: POST

Consumes:

application/json
text/json
application/xml
text/xml
application/x-www-form-urlencoded

Produces:

application/json
text/json
application/xml
text/xml

Authentication

This endpoint requires API key authentication. The API key must be included in the request header:

Header:
X-ApiKey: your_api_key_here

Request Parameters

The request body must be a JSON object that follows the EnqueueCommunicationsRequestModel schema.

Request Body Schema:

{ "communications": [ { "clientMessageId": "string", "recipient": "string", "content": { "$type": "string" } } ] }

Request Fields

Field	Type	Required	Description
communications	Array	Yes	A list of communications to be enqueued.
clientMessageId	String	Yes	A unique identifier for the message assigned by the client.
recipient	String	Yes	The recipient's contact information.
content	Object	Yes	The content of the communication. The `$type` field must be specified.

Content Types

`$type` Value	Required Fields
SMSProject	`projectId` (integer), `placeholders` (array of strings)
WhatsappProject	`projectId` (integer), `placeholders` (array of strings)
SMSFromAlpha	`sender` (string, max length 11), `text` (string)

Response

If the request is successful, the API returns a JSON response with details of the enqueued communications.

Response Schema:

{ "results": { "clientMessageId1": { "trackingId": "32-character-hexadecimal-string", "success": true, "isTransientError": false } } }

Response Fields

Field	Type	Description
clientMessageId	Object	The key corresponds to the `clientMessageId` provided in the request.
trackingId	String	A unique 32-character hexadecimal identifier assigned to the enqueued message.
success	Boolean	Indicates if the request was successful.
isTransientError	Boolean	If `false`, the error is permanent, and the message should not be retried. If `true`, the error is transient, and retrying may succeed. This field is only present if `success` is `false`.

Placeholder and Content Ratio

For SMSProject and WhatsappProject types, the content text (excluding placeholders) must be pre-reviewed and pre-approved. The majority of the textual content must reside within the project's pre-approved template to comply with platform policies.

Placeholders should only be used for dynamic values such as names, order numbers, or appointment times.
This approach aligns with best practices for template-based messaging, where the core content remains fixed while allowing limited dynamic input.

Example Requests and Responses

Example 1: SMSProject Content

Request:

{ "communications": [ { "clientMessageId": "12345", "recipient": "46701234567", "content": { "$type": "SMSProject", "projectId": 123, "placeholders": ["John", "Order #5678"] } } ] }

Response:

{ "results": { "12345": { "trackingId": "abcdef1234567890abcdef1234567890", "success": true, "isTransientError": false } } }

Example 2: WhatsappProject Content

Request:

{ "communications": [ { "clientMessageId": "67890", "recipient": "46709876543", "content": { "$type": "WhatsappProject", "projectId": 789, "placeholders": ["Jane", "Delivery on Monday"] } } ] }

Response:

{ "results": { "67890": { "trackingId": "123456abcdef7890123456abcdef7890", "success": true, "isTransientError": false } } }

Example 3: SMSFromAlpha Content

Request:

{ "communications": [ { "clientMessageId": "54321", "recipient": "46705678901", "content": { "$type": "SMSFromAlpha", "sender": "Wiraya", "text": "Your verification code is 123456" } } ] }

Response:

{ "results": { "54321": { "trackingId": "7890abcdef1234567890abcdef123456", "success": true, "isTransientError": false } } }

Error Handling

Common Errors

HTTP Status Code	Error Message	Description
400 Bad Request	Invalid input format	The request body contains invalid data.
401 Unauthorized	Invalid API Key	The API key is missing or incorrect.
500 Internal Server Error	Server error	An unexpected error occurred on the server.

Additional Notes

Ensure that the clientMessageId is unique for each request to prevent duplicate message processing.
If isTransientError is true, retrying the request may resolve the issue.
The $type field in the content object should specify the communication type (SMSProject, WhatsappProject, or SMSFromAlpha).
The sender field for SMSFromAlpha must not exceed 11 characters.