SMS¶

Before you begin¶

Prepare the recipient phone number and either message content or a template ID. When template_id is sent, it takes precedence over message.

Review Authentication and replace all example values, including template IDs and dates, before submitting a request.

Request workflow¶

Prepare the HTTP request shown below.
Complete the required fields and only the optional fields needed by your integration.
Submit the request and inspect its response.
Retain the returned identifier, when provided, and check the result before repeating a delivery.

HTTP request to send SMS¶

POST https://send.obmessage.ai/api/v1/sms
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "phone": "string",
    "message": "string",
    "reference": "string",
    "group": "string",
    "template_id": "string",
    "not_sent_after": "string",
    "fields": [
        {
            "name": "string",
            "value": "string",
            "short": true
        }
    ]
}

Try it in Postman

Field description¶

Required nested fields apply when their containing object or array element is included.

Field	Description	Required
phone	Recipient phone number in E.164 format.	Yes
message	Content of the message to be sent.	No
reference	Message reference ID.	No
template_id	ID of the created template. If this field is sent, `message` is ignored.	No
not_sent_after	Any message processed after the specified time will be marked with the `cancelled` status. The time format must be `UTC`. This field is not required, but it is recommended to avoid sending notifications outside regulated hours. See the policies section.	No
group	Group reference ID for the message.	No
fields	Array of dynamic fields associated with the message.	No
fields.name	Field name.	Yes
fields.value	Field value.	Yes
fields.short	Indicates whether the field value should be shortened.	No

Sample JSON payload¶

POST https://send.obmessage.ai/api/v1/sms
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "phone": "+18099999999",
    "message": "Hello World",
    "reference": "8151",
    "group": "obm-api",
    "template_id": "60b7720a-8129-4f31-9ea9-457f77cde3de",
    "not_sent_after": "2024-02-12T23:30:59Z",
    "fields": [
        {
            "name": "cuota",
            "value": "138.98"
        }
    ]
}

Try it in Postman

Response¶

The endpoint returns 200 OK with the following JSON response. Inspect status; this response alone does not confirm delivery to the recipient.

{
    "id": "string",
    "phone": "string",
    "reference": "string",
    "group": "string",
    "status": "string",
    "created_at": "string"
}

Response field description¶

Field	Description
id	Message identification code.
phone	Phone number, corresponding to the same value sent.
reference	Message reference ID, corresponding to the same value sent.
group	Group reference ID, corresponding to the same value sent.
created_at	Date when the message is received, in RFC 3339 format.
status	Current message status. Possible values are: `received` and `error`.

Check results and errors¶

Use the returned id in Check status. Keep the reference and group used by your integration to locate the records. For unsuccessful requests, see Error responses.