Sending SMS

The Send SMS endpoint allows you to broadcast SMS to one or more contacts directly from your code. This is useful for bulk messaging, alerts, notifications, and marketing campaigns.

Endpoint

• URL: /sms/a2p/send
• Method: POST

Request Headers

Include the following headers in your request:

• Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json

Request Body

The request body should be a JSON object containing the following fields:

Field	Data Type	Description
recipients	Array[String]	A list of one or more phone numbers to receive the SMS. Each number must be in international format (e.g., "2348181234567").
text	String	The SMS message content. Make sure it's within the allowed character limit for SMS (typically 160 characters for a single SMS).
sender	String	The sender name that appears as the sender of the SMS. Must be pre-registered on Cecula DartPro. If your traffic is financial or government-related, additional compliance steps may be required. Contact support for assistance.
flash	Boolean	(Optional) Set to true to send a flash message. Flash messages appear directly on the recipient’s screen without being stored. Defaults to false.

Sample Request

curl --location 'https://app.cecula.com/api/sms/a2p/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipients": ["2348181234567", "2348141234567"],
  "text": "Sample TexT",
  "sender": "Cecula",
  "flash": false
}'

Sample Successful Response

{
  "recipients": [
    {
      "id": "b8bfb980-357a-4a39-863a-1b27c1f191d5",
      "mobile": "2348181234567",
      "status": "ACK",
      "code": 1801
    },
    {
      "id": "5f019c1e-e2ae-4dc7-b52d-3c748e96c97e",
      "mobile": "2348141234567",
      "status": "ACK",
      "code": 1801
    }
  ],
  "messageReference": "93b71cc8-744d-46e3-a2f4-96ace66ea738"
}

💡 Need Delivery Report?

Cecula API offers two methods of getting delivery reports:

Periodic Polling: If you are integrating a stand-alone application, See Guide on how to use the highlighted id to retrieve delivery status for the sent messages.

Webhook Delivery Report: For cloud application, simply register a webhook where we'll POST your reports. Learn More.

Response Fields

Field	Data Type	Description
recipients	Array[Object]	A list of recipients and their respective message status.
recipients[].id	String	A unique identifier for the message sent to the specific recipient. Useful for tracking delivery.
recipients[].mobile	String	The recipient’s mobile number.
recipients[].status	String	The status of the message for that recipient. ACK indicates it was accepted.
recipients[].code	Integer	Response code. 1801 generally indicates a successful message broadcast. See Responses for detailed list of response codes.
messageReference	String	A unique reference for the entire message transaction, used to track the broadcast.

Special Notes on Sender Name Registration

Before using a sender name, you must register it on the Cecula DartPro platform:

1. Login to Cecula DartPro.
2. Navigate to Identities.
3. Register the sender names you plan to use.
4. Important: Sender names must be approved by telecom providers before use. For government or financial traffic, additional compliance steps may be required. Contact support if you have such traffic.

Example Use Cases

1. Send SMS to a Single Recipient

curl --location 'https://app.cecula.com/api/sms/a2p/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipients": ["2348181234567"],
  "text": "Sample TexT",
  "sender": "Cecula",
  "flash": false
}'

2. Send SMS to Multiple Recipients

curl --location 'https://app.cecula.com/api/sms/a2p/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipients": ["2348181234567", "2348141234567"],
  "text": "Reminder: Our sale ends tomorrow!",
  "sender": "Cecula",
  "flash": false
}'

3. Send a Flash SMS

A Flash SMS is a special type of SMS message that bypasses the Inbox and immediately appears on the recipient's screen without requiring them to open it.

Hint

Flash SMS is ideal for One Time Passwords (OTP), security alerts, and emergency notifications.

To broadcase flash sms, set flash parameter to True. See higlighted adjustment.

curl --location 'https://app.cecula.com/api/sms/a2p/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipients": ["2348181234567"],
  "text": "Urgent: Please call back immediately.",
  "sender": "Cecula",
  "flash": true
}'

4. Schedule SMS (Additional Parameter)

To schedule the sms for broadcast at a future time or date, you can add a broadcastTime field to the request body. The schedule field would specify the date and time at which the message should be sent.

curl --location 'https://app.cecula.com/api/sms/a2p/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipients": ["2348181234567"],
  "text": "Happy Holidays from Cecula!",
  "sender": "Cecula",
  "flash": false,
  "broadcastTime": "2024-12-25T09:00:00Z"
}'

This sends the message on December 25, 2024, at 09:00 AM UTC.