Send Template SMS

The Send Template SMS endpoint allows you to broadcast personalized messages to multiple contacts by utilizing pre-defined templates. Template messages are useful when you want to send standardized messages where only certain variables change per recipient. This ensures consistent messaging while allowing flexibility in the variables.

Endpoint

• URL: /sms/a2p/template/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[Object]	An array of recipient objects. Each recipient object contains the mobile number of the recipient and a data object. The data object contains the variables that correspond to placeholders in the template.
template	String	The template ID that has been created on Cecula DartPro. This ID links the message body to be broadcast.
sender	String	The sender name that appears as the sender of the SMS. Must be pre-registered on Cecula DartPro.
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.

Example Request Body

curl --location 'https://app.cecula.com/api/sms/a2p/template/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "recipients": [
        {
        "mobile": "2348061234567",
            "data": {
                "customer_name": "John Doe",
                "subscription_plan": "Monthly",
                "payment_due": "NGN 100,000",
                "due_date": "Feb 20th, 2025"
            }
        },
        {
        "mobile": "2348079876543",
            "data": {
                "customer_name": "Jane Smith",
                "subscription_plan": "Annual",
                "payment_due": "NGN 1,200,000",
                "due_date": "Dec 31st, 2024"
            }
        }
    ],
    "template": "c628b9a8-8869-49a6-89ec-58020136abef",
    "sender": "Cecula",
    "flash": false
}'

Sample Successful Response

[
    {
        "recipients": [
            {
                "id": "08c38300-d510-46f8-bb55-caead795f387",
                "mobile": "2348061234567",
                "status": "ACK",
                "code": 1801
            }
        ],
        "messageReference": "46bb785f-b7fb-4f61-994c-b8b6030ac3fd"
    },
    {
        "recipients": [
            {
                "id": "e89c0d91-af38-406e-ae8b-9cd3117408ba",
                "mobile": "2348079876543",
                "status": "ACK",
                "code": 1801
            }
        ],
        "messageReference": "7960df62-400c-4626-88e5-c011bf8b728a"
    }
]

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.
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.
messageReference	String	A unique reference for the entire message transaction, used to track the broadcast.

Message Body

The following is the message body that will be created from the provided template and data:

Template Body:

Dear [customer_name],
Your [subscription_plan] subscription plan of [payment_due] will be due for renewal by [due_date].
Please make prompt payment to avoid service interruption.

Example Message 1:

Dear John Doe,
Your Monthly subscription plan of NGN 100,000 will be due for renewal by Feb 20th, 2025.
Please make prompt payment to avoid service interruption.

Example Message 2:

Dear Jane Smith,
Your Annual subscription plan of NGN 1,200,000 will be due for renewal by Dec 31st, 2024.
Please make prompt payment to avoid service interruption.

Use-Cases

1. Individuals: This is ideal when you need to send a personalized SMS to one individual, such as notifying a customer about an upcoming bill used in the samples above, a reminder for an appointment, or a transaction alert. This simplifies the process of personalizing messages without building the text on-the-fly in your code.

2. Groups: Useful for sending the same message to a group of recipients, each with personalized content. This scenario is perfect for broadcasting information such as subscription renewals, payment reminders, or promotional messages to a list of customers with varying details, like due dates or amounts. The ability to reuse a single message template saves time and prevents code repetition.

Sending to a Single Recipient

curl --location 'https://app.cecula.com/api/sms/a2p/template/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "recipients": [
        {
        "mobile": "2348061234567",
            "data": {
                "customer_name": "John Doe",
                "subscription_plan": "Monthly",
                "payment_due": "NGN 100,000",
                "due_date": "Feb 20th, 2025"
            }
        }
    ],
    "template": "c628b9a8-8869-49a6-89ec-58020136abef",
    "sender": "Cecula",
    "flash": false
}'

Sending to Multiple Recipients

curl --location 'https://app.cecula.com/api/sms/a2p/template/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "recipients": [
        {
        "mobile": "2348061234567",
            "data": {
                "customer_name": "John Doe",
                "subscription_plan": "Monthly",
                "payment_due": "NGN 100,000",
                "due_date": "Feb 20th, 2025"
            }
        },
        {
        "mobile": "2348079876543",
            "data": {
                "customer_name": "Jane Smith",
                "subscription_plan": "Annual",
                "payment_due": "NGN 1,200,000",
                "due_date": "Dec 31st, 2024"
            }
        }
    ],
    "template": "c628b9a8-8869-49a6-89ec-58020136abef",
    "sender": "Cecula",
    "flash": false
}'

Scheduling Template Messages

You can schedule template messages by adding a broadcastTime field in your request body. This field specifies the time when the message should be sent.

curl --location 'https://app.cecula.com/api/sms/a2p/template/send' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "recipients": [
        {
        "mobile": "2348061234567",
            "data": {
                "customer_name": "John Doe",
                "subscription_plan": "Monthly",
                "payment_due": "NGN 100,000",
                "due_date": "Feb 20th, 2025"
            }
        }
    ],
    "template": "c628b9a8-8869-49a6-89ec-58020136abef",
    "sender": "Cecula",
    "flash": false,
    "broadcastTime": "2024-12-25T09:00:00Z"
}'

This message will be broadcast on December 25, 2024, at 09:00 AM UTC.