v1.0

Routeon Broadcast API

Authentication

API authentication is implemented using the API key, which must be added to the X-API-Key header.

The API key will be generated in your personal account in the API Accesses interface. Specify recipients (for contacts) and/or broadcast (for broadcasts) for Scopes.

Response

If the request is successful, the API will respond with a 200 OK code, with the details in the response body.

If the request is unsuccessful, the API will respond with the appropriate HTTP code, with details in the response body.

Working with templates

Connection

API URL path:

https://{{URL}}/api/v1/broadcast/templates

Template Operations

Get Template List

GET /api/v1/broadcast/templates

Description

Retrieves a paginated list of available broadcast templates for the authenticated company.

Parameters
Field Type Reqd. Description
limit integer No Maximum number of entries. Default value: 10.
offset integer No Offset for the list (which entry to start output from). Default value: 0.
Response

Possible responses:

  • 200 - OK - Successful. The body contains ListResource«ExtApiTemplateDto» data model.
  • 400 - Bad Request - Invalid request. The body contains ApiError data model.
  • 401 - Unauthorized - Request lacks valid authentication credentials.
  • 403 - Forbidden - Access denied.
  • 500 - Internal Server Error - Server-side error.
Example

Request

GET https://{{URL}}/api/v1/broadcast/templates?limit=2

Response

200 OK + Body
{
    "resourceList": [
        {
            "id": 1670,
            "name": "Test_template",
            "createdAt": "2024-08-09T12:27:55.893652Z",
            "updatedAt": "2024-08-09T12:27:57.81028Z",
            "channel": 4,
            "fullRecordCount": 0,
            "content": "[]"
        },
        {
            "id": 1669,
            "name": "new_template",
            "createdAt": "2024-08-27T13:01:08.252762Z",
            "updatedAt": "2024-08-27T13:01:08.11515Z",
            "channel": null,
            "fullRecordCount": 0,
            "content": "[{"order":0,"channelType":1,"senderId":"4930609859535","contentPattern":"{\"preview_url\":true,\"recipient_type\":\"individual\",\"type\":\"text\",\"text\":{\"body\":\"{{attribute.phoneNumber}}\"}}","deliveryCondition":"DELIVERY_SUCCESS","timeout":600}]"
        }
    ],
    "size": 634,
    "limit": 2,
    "offset": 0
}

Get Template Details

GET /api/v1/broadcast/templates/{id}

Description

Retrieves detailed information about a specific template.

Parameters
Field Type Reqd. Description
id string Yes ID of the template
Response

Possible responses:

  • 200 - OK - Successful. The body contains ExtApiTemplateDto data model.
  • 400 - Bad Request - Invalid ID format.
  • 401 - Unauthorized - Request lacks valid authentication credentials.
  • 403 - Forbidden - Access denied or company mismatch.
  • 404 - Not Found - Template not found.
  • 500 - Internal Server Error - Server-side error.
Example

Request

GET https://{{URL}}/api/v1/broadcast/templates/1670

Response

200 OK + Body
{
    "id": 1670,
    "name": "Summer promotion",
    "description": "Summer promotion template",
    "extraRecipientList": [
        "4915735987904"
    ],
    "filterList": [],
    "tags": [],
    "contentType": 1,
    "rcsCheckFlag": false,
    "content": {
        "flowSteps": [
            {
                "order": 0,
                "channelType": 1,
                "senderId": "sms_sender",
                "contentPattern": "I am just a simple template for online documentation",
                "deliveryCondition": "DELIVERY_SUCCESS",
                "timeout": 259200
            }
        ]
    },
    "createdAt": "2024-08-09T12:27:55.893652Z",
    "updatedAt": "2024-08-09T12:27:57.81028Z"
}

Create Template

POST /api/v1/broadcast/templates

Description

Creates a new broadcast template. Content may require moderation depending on company policies.

Request Body

ExtApiTemplateDto object with required fields:

Field Type Reqd. Description
name string Yes Template name
contentType integer Yes 1: Fallback, 2: Chat Bot, 3: RCS Capability Check
content object Yes Content configuration (flowSteps, scenario, rcsCapabilityCheck)
rcsCheck boolean No Whether to perform RCS capability check (for Fallback content type only)
description string No Optional description
tags array No List of tags for categorization
filterList array No List of filters to apply
extraRecipientList array No List of exact recipient phone numbers
Response

Possible responses:

  • 200 - OK - Successful creation. The body contains the created ExtApiTemplateDto.
  • 400 - Bad Request - Invalid input data or missing required fields.
  • 401 - Unauthorized - Request lacks valid authentication credentials.
  • 403 - Forbidden - Access denied.
  • 500 - Internal Server Error - Server-side error.
Example

Request

POST https://{{URL}}/api/v1/broadcast/templates

Request Body

{
    "name": "Summer promotion",
    "description": "Template for summer product line promotion",
    "extraRecipientList": [],
    "filterList": [],
    "tags": ["promo"],
    "contentType": 1,
    "content": {
        "flowSteps": [
            {
                "channelType": 1,
                "senderId": "sms_sender",
                "contentPattern": "I am just a simple template for online documentation",
                "deliveryCondition": "DELIVERY_SUCCESS",
                "timeout": 259200
            }
        ]
    }
}

Response

200 OK + Body
{
    "id": 1671,
    "name": "Summer promotion",
    "description": "Template for summer product line promotion",
    "extraRecipientList": [],
    "filterList": [],
    "tags": ["promo"],
    "contentType": 1,
    "rcsCheckFlag": false,
    "content": {
        "flowSteps": [
            {
                "order": 0,
                "channelType": 1,
                "senderId": "sms_sender",
                "contentPattern": "I am just a simple template for online documentation",
                "deliveryCondition": "DELIVERY_SUCCESS",
                "timeout": 259200
            }
        ]
    },
    "createdAt": "2024-08-09T12:27:55.893652Z",
    "updatedAt": "2024-08-09T12:27:55.893652Z"
}

Update Template

PUT /api/v1/broadcast/templates/{id}

Description

Updates an existing template. Partial updates are supported (null fields are ignored). Changing content type requires full content specification. May trigger moderation.

Parameters
Field Type Reqd. Description
id string Yes ID of the template
Request Body

ExtApiTemplateDto object with fields to update (null fields will be ignored):

Same fields as Create Template, all optional for partial updates.

Response

Possible responses:

  • 200 - OK - Successful update. The body contains the updated ExtApiTemplateDto.
  • 400 - Bad Request - Invalid input data or content type change without content.
  • 401 - Unauthorized - Request lacks valid authentication credentials.
  • 403 - Forbidden - Access denied or company mismatch.
  • 404 - Not Found - Template not found.
  • 500 - Internal Server Error - Server-side error.
Example

Request

PUT https://{{URL}}/api/v1/broadcast/templates/1670

Request Body

{
    "name": "Summer Promotion 2024",
    "description": "Updated template for summer campaign"
}

Response

200 OK + Body
{
    "id": 1670,
    "name": "Summer promotion 2024",
    "description": "Updated template for summer campaign",
    "extraRecipientList": [],
    "filterList": [],
    "tags": ["promo"],
    "contentType": 1,
    "rcsCheckFlag": false,
    "content": {
        "flowSteps": [
            {
                "order": 0,
                "channelType": 1,
                "senderId": "sms_sender",
                "contentPattern": "I am just a simple template for online documentation",
                "deliveryCondition": "DELIVERY_SUCCESS",
                "timeout": 259200
            }
        ]
    },
    "createdAt": "2024-08-09T12:27:55.893652Z",
    "updatedAt": "2024-08-10T10:20:30.456789Z"
}

Delete Template

DELETE /api/v1/broadcast/templates/{id}

Description

Deletes a template from the system. This action is irreversible.

Parameters
Field Type Reqd. Description
id string Yes ID of the template
Response

Possible responses:

  • 204 - No Content - Successful deletion.
  • 400 - Bad Request - Invalid ID format.
  • 401 - Unauthorized - Request lacks valid authentication credentials.
  • 403 - Forbidden - Access denied.
  • 404 - Not Found - Template not found.
  • 500 - Internal Server Error - Server-side error.
Example

Request

DELETE https://{{URL}}/api/v1/broadcast/templates/1670

Response

204 No Content

Working with broadcasts

Connection

API URL path:

https://{{URL}}/api/v1/broadcast/broadcasts

Requests to API are sent using the POST method.

Webhook

To receive notifications containing the results of sending, delivering and reading messages, you need to register the URL where your equipment expects these notifications as the Webhook URL of the corresponding connection in your personal account in the API Accesses.

Webhook-call body

Field Type Reqd. Description
status string Yes Updated broadcast status.
webhook string Yes Webhook URL to which broadcast status reports will be sent.
broadcastId integer Yes Broadcast ID.
message string No Error description. Returns null if no errors were detected during the broadcast.

Launching broadcast

Method and endpoint

POST /api/v1/broadcast/broadcasts

Description

It is used to launch a broadcast.

Parameters

ExtApiBroadcastRequestDto data model.

Response

Possible responses:

  • 200 — OK — Successful. The body will be empty.
  • 400 — Bad Request — Invalid request. The body contains ApiError data model.
  • 401 — Unauthorized — Request lacks valid authentication credentials. The body contains ApiError data model.
  • 403 — Forbidden — Access denied. The body contains ApiError data model.
  • 404 — Not Found — Templates not found. The body contains ApiError data model.
  • 500 — Internal Server Error — Server-side error. The body contains ApiError data model.

Example 1

Request to immediately launch a broadcast using template target filters.

Request

POST https://{{URL}}/api/v1/broadcast/broadcasts

Body

{
    "templateId": 3091,
    "launchTime": "",
    "webhook": "https://webhook.site/9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a"
}

Response

200 OK

Example 2

Request to create a broadcast list planned for the future, indicating the recipient's phone number.

Request

POST https://{{URL}}/api/v1/broadcast/broadcasts

Body

{
    "templateId": 3091,
    "launchTime": "2024-08-30T09:14:45.410958Z",
    "webhook": "https://webhook.site/9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
    "recipientsList": [
        {
            "phoneNumber": "4915735987904"
        }
    ]
}

Response

200 OK

Example 3

If the required parameter phoneNumber is not specified in the request, the API will respond with code 400.

Request POST https://{{URL}}/api/v1/broadcast/broadcasts

Body

{
    "templateId": 3091,
    "launchTime": "2024-08-30T09:14:45.410958Z",
    "webhook": "https://webhook.site/9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
    "recipientsList": [
        {
            "name": "Alice"
        }
    ]
}

Response 400 Bad Request + Body

{
    "execId": null,
    "key": null,
    "code": null,
    "message": "Phone number can't be null or empty",
    "args": null
}

Example 4

To immediately launch a broadcast without using a template, the API caller must specify the broadcast's content in the payload element of the request body.

Request:

POST https://{{URL}}/api/v1/broadcast/broadcasts

Request body for SMS broadcast:

{
    "name": "Summer sale",
    "description": "Summer product line sale",
    "launchTime": "2025-08-30T09:14:45.410958Z",
    "webhook": "https://webhook.site/9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
    "recipientsList": [
        {"phoneNumber": "4915735987904"},
        {"phoneNumber": "4948735987296"}
    ],
    "payload": {
        "contentType": 1,
        "contentSettings": {
            "flowSteps": [
                {
                    "channelType": 1,
                    "senderId": "smsGate",
                    "timeout": 172800,
                    "deliveryCondition": "SUBMIT_SUCCESS",
                    "contentPattern": "Hello and welcome to our summer sale starting today!"
                }
            ]
        }
    }
}

Response:

200 OK

Notes:

  • name and description are optional fields for immediate broadcasts without templates.
  • If the name attribute is not provided, the system will automatically generate a value for the broadcast name.
  • launchTime is an optional field used when the broadcast must be scheduled for a future time.
  • The webhook attribute must be set to a webhook URL to receive the broadcast results.
  • The recipientsList attribute must contain one or more recipient objects with the phoneNumber attribute containing the recipient's phone number as a value.

For SMS broadcasts, the payload object must include the following elements:

  1. contentType attribute with value 1 (Fallback)
  2. contentSettings object containing a nested flowSteps array

The flowSteps array must contain at least one object with these required attributes:

  • channelType: Set to 1 (SMS)
  • senderId: Identifier of the sender for this step
  • timeout: Number of seconds to wait for delivery (in this example, 172800 seconds = 2 days)
  • deliveryCondition: Either SUBMIT_SUCCESS (for successful SMS submission) or DELIVERY_SUCCESS (for successful delivery)
  • contentPattern: The broadcast message content
Open API Playground Download spec

ExtAPI Broadcasts

Broadcast Controller

POST /api/v1/broadcast/broadcasts launch

ExtAPI Templates

Provides operations for managing templates in the system.

GET /api/v1/broadcast/templates Get list of Templates POST /api/v1/broadcast/templates Create a new Template GET /api/v1/broadcast/templates/{id} Get Template PUT /api/v1/broadcast/templates/{id} Update Template DELETE /api/v1/broadcast/templates/{id} Delete Template