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",
"updatedAt": null,
"channel": null,
"fullRecordCount": 0,
"content": "[{"order":0,"channelType":"WHATSAPP","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:

`http://{{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