Campaign API v1.0.0

21 minutes of reading

1. Introduction #

1.1 Overview #

Business Messenger (BM) Campaign API is a standard REST HTTP API with JSON payload. It can be used to programmatically manage BM campaign data. BM API authorization is implemented as the industry-standard OAuth2 protocol.

Here you can download the Campaign API Swagger file for use in your development project.

The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/news/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

The subject domain of an endpoint URL depends on your domain used to access our services.
Please check with your CRM Account Manager, what is the subject domain you should use.

1.2 Getting Credentials #

In order to be able to use the API, you need to provide a name for your custom app, IP address from which you will be authorizing the app and the BM account name whose contacts data your app will be managing. It is expected that your app will be a server-side implementation and as such will use the OAuth2 client credentials grant type.
In return, the support team will create an API account for your app and you will be given: client_id and client_secret credentials.

1.3 Authorization #

In order to be able to call any API endpoint, you need to obtain a valid access token. Each access token has an expiration time so you need to obtain a new one if the existing one is expired. Here’s a CURL example of how an access token can be obtained (please replace CLIENT_ID and CLIENT_SECRET with the ones you were given in the previous step):

curl https://accounts{separator}{platform_domain}/oauth2/access-token -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'

Note: A domain is presented with placeholders as https://accounts{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

If the parameters are valid, and the call is made from the authorized IP address, the server will respond with JSON containing the access token:

{"access_token":"ACCESS_TOKEN","token_type":"Bearer","expires_in":604800}

For more information please refer to the OAuth2 Authentication Guidelines page.

1.4 Cloning Existing Campaign #

An existing campaign, e.g. draft one, can be cloned and activated, and the call can be as simple as:

  curl -X 'POST' \
    'https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/campaigns' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS_TOKEN' \
    -d '{
    "clone_uuid": "CLONE_UUID",
    "template_vars": {
      "temp": "-22C",
      "wind": "100km/h"},
    "name": "Bad weather conditions"
    }'

CLONE_UUID is an UUID of an existing campaign we want to clone from. Replace SERVICE_UUID, ACCESS_TOKEN, CLONE_UUID with proper values. template_vars is a simple dictionary of key/value pairs. It is expected that the campaign you are cloning from, has variables in the text content {temp}, {wind}. Note that name is optional. Additional fields depend on your wish what exact fields you want to overwrite compared to the existing campaign you are cloning from.

2. Methods Overview #

Campaign Management Endpoints. List, Fetch, Create, Clone, Update, Stop/Resume Business Messenger Campaigns.

POST/services/{serviceUuid}/campaigns

Creates or clones a Campaign.

GET/services/{serviceUuid}/campaigns

Gets a list of Campaigns.

GET/services/{serviceUuid}/campaigns/{campaignUuid}

Gets a Campaign by UUID.

PUT/services/{serviceUuid}/campaigns/{campaignUuid}

Updates a Campaign.

PATCH/services/{serviceUuid}/campaigns/{campaignUuid}

Changes a campaign Status – toggle active/stopped.

DELETE/services/{serviceUuid}/campaigns/{campaignUuid}

Deletes a Campaign.

3. Methods Details #

Campaign Management Endpoints. List, Fetch, Create, Clone, Update, Stop/Resume BM Campaigns.

3.1 Create or Clone a Campaign #

POST/services/{serviceUuid}/campaigns

Creates or clones a Campaign.

Method Overview #

The method creates or clones a Campaign.

Example #

Create a new SMS campaign to be executed once on 1st of May, 2024 at 17:05 UTC timezone. Message content includes a contact variable for a contact’s first name. The messages will be sent to contacts from the defined list per recipient_lists.

  curl -X 'POST' \
    'https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/campaigns' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "name": "New Campaign",
    "status": "active",
    "sending_type": "sms",
    "schedule_type": "once",
    "schedule_rrule": "2024-05-01 17:05:00",
    "template": "Hello @first_name",
    "sender": "+41587000000",
    "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618"
    }'

Parameters #

Name	Type	Description
serviceUuid (required)	string (path)	Service (BM Account) UUID.
body (required)	object (body)	Campaign to add. Find below CampaignCreate data model description.

Data Parameters #

CampaignCreate post data object example

{
  "clone_uuid": "1592695e-c1b1-11ee-b153-774c9d3a7957",
  "template_vars": {
    "temp": "-22C",
    "wind": "100km/h"
  },
  "name": "Bad weather conditions"
}

Responses #

Code	Description	Links
201	New Campaign response.	No links
400	Invalid request.	No links

Success Response 201: New Campaign Response #

{
  "name": "New Campaign",
  "status": "active",
  "sending_type": "sms",
  "schedule_type": "once",
  "schedule_rrule": "2024-05-01 17:05:00",
  "template": "Hello world",
  "webpush_title": "string",
  "webpush_body": "string",
  "webpush_target_url": "string",
  "webpush_icon": "string",
  "webpush_image": "string",
  "sender": "+41587000000",
  "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618",
  "query_type": "segmentation",
  "query": "{\"segmentation\":[{\"operator\":\"OR\",\"rules\":[{\"field\":\"subscription_options_in\",\"condition\":\"in\",\"value\":[\"7c4c1e07-4c65-4861-ab82-9f8fd9cd3913\",\"94bb60a3-7b4b-4614-913c-0a2760e5f633\"],\"operator\":\"AND\"}]}]}\n",
  "uuid": "string",
  "created_dt": "2024-02-05T09:34:11.327Z",
  "updated_dt": "2024-02-05T09:34:11.327Z",
  "next_dt": "2024-02-05T09:34:11.327Z",
  "last_dt": "2024-02-05T09:34:11.327Z"
}

Error Response 400: Invalid request #

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.2 Get a List of Campaigns #

GET/services/{serviceUuid}/campaigns

Gets a list of Campaigns.

Method Overview #

The method gets a list of Campaigns with optional filters and sort order.

Example #

Read draft SMS campaigns, ordered by created date descending.

  curl -X 'GET' \
    'https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/campaigns?sending_type=sms&status=draft&sort=-created_dt' \
    -H 'accept: application/json'

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters #

Name	Type	Description
serviceUuid (required)	string (path)	Service (BM Account) UUID.
sending_type	string (query)	Search by messaging channel. Available values: sms, webpush, email, telegram, rbm, viber, whatsapp.
status	string (query)	Search by status. Available values: active, stopped, finished, draft.
fields	array[string] (query)	Include optional fields in the response. Possible values: tasks, messages.
sort	array[string] (query)	Define order by columns.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.

Responses #

Code	Description	Links
200	List of Campaigns.	No links.

Success Response 200: List of Campaigns #

{
  "data": [
    {
      "name": "New Campaign",
      "status": "active",
      "sending_type": "sms",
      "schedule_type": "once",
      "schedule_rrule": "2024-05-01 17:05:00",
      "template": "Hello world",
      "webpush_title": "string",
      "webpush_body": "string",
      "webpush_target_url": "string",
      "webpush_icon": "string",
      "webpush_image": "string",
      "sender": "+41587000000",
      "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618",
      "query_type": "segmentation",
      "query": "{\"segmentation\":[{\"operator\":\"OR\",\"rules\":[{\"field\":\"subscription_options_in\",\"condition\":\"in\",\"value\":[\"7c4c1e07-4c65-4861-ab82-9f8fd9cd3913\",\"94bb60a3-7b4b-4614-913c-0a2760e5f633\"],\"operator\":\"AND\"}]}]}\n",
      "uuid": "string",
      "created_dt": "2024-02-05T09:41:46.187Z",
      "updated_dt": "2024-02-05T09:41:46.187Z",
      "next_dt": "2024-02-05T09:41:46.187Z",
      "last_dt": "2024-02-05T09:41:46.187Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

3.3 Get a Campaign by UUID #

GET/services/{serviceUuid}/campaigns/{campaignUuid}

Gets a Campaign by UUID.

Method Overview #

The method fetches an existing campaign by its UUID.

Example #

  curl -X 'GET' \
    'https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/campaigns/CAMPAIGN_UUID' \
    -H 'accept: application/json'

Parameters #

Name	Type	Description
serviceUuid (required)	string (path)	Service (BM Account) UUID.
campaignUuid (required)	string (path)	Campaign UUID.
fields	array[string] (query)	Include optional fields in the response. Possible values: tasks, messages.

Responses #

Code	Description	Links
200	Campaign data.	No links.
404	Resource not found.	No links.
default	Unexpected error.	No links.

Success Response 200: Campaign data #

{
  "name": "New Campaign",
  "status": "active",
  "sending_type": "sms",
  "schedule_type": "once",
  "schedule_rrule": "2024-05-01 17:05:00",
  "template": "Hello world",
  "webpush_title": "string",
  "webpush_body": "string",
  "webpush_target_url": "string",
  "webpush_icon": "string",
  "webpush_image": "string",
  "sender": "+41587000000",
  "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618",
  "query_type": "segmentation",
  "query": "{\"segmentation\":[{\"operator\":\"OR\",\"rules\":[{\"field\":\"subscription_options_in\",\"condition\":\"in\",\"value\":[\"7c4c1e07-4c65-4861-ab82-9f8fd9cd3913\",\"94bb60a3-7b4b-4614-913c-0a2760e5f633\"],\"operator\":\"AND\"}]}]}\n",
  "uuid": "string",
  "created_dt": "2024-02-06T14:15:55.403Z",
  "updated_dt": "2024-02-06T14:15:55.403Z",
  "next_dt": "2024-02-06T14:15:55.403Z",
  "last_dt": "2024-02-06T14:15:55.403Z"
}

Error Response 404: Resource not found #

Error Response Unexpected Error: Default #

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.4 Update a Campaign #

PUT/services/{serviceUuid}/campaigns/{campaignUuid}

Updates a Campaign.

Method Overview #

The method updates an existing campaign identified by UUID. It has the same payload as POST request.

Parameters #

Name	Type	Description
serviceUuid (required)	string (path)	Service (BM Account) UUID.
campaignUuid (required)	string (path)	Campaign UUID.
body (required)	object (body)	Campaign data to be updated. Find below CampaignUpdate data model description.

Data Parameters #

Campaign data example

{
  "name": "New Campaign",
  "status": "active",
  "sending_type": "sms",
  "schedule_type": "once",
  "schedule_rrule": "2024-05-01 17:05:00",
  "template": "Hello world",
  "webpush_title": "string",
  "webpush_body": "string",
  "webpush_target_url": "string",
  "webpush_icon": "string",
  "webpush_image": "string",
  "sender": "+41587000000",
  "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618",
  "query_type": "segmentation",
  "query": "{\"segmentation\":[{\"operator\":\"OR\",\"rules\":[{\"field\":\"subscription_options_in\",\"condition\":\"in\",\"value\":[\"7c4c1e07-4c65-4861-ab82-9f8fd9cd3913\",\"94bb60a3-7b4b-4614-913c-0a2760e5f633\"],\"operator\":\"AND\"}]}]}\n"
}

Responses #

Code	Description	Links
200	Campaign updated.	No links.
400	Invalid request.	No links.
404	Campaign not found.	No links.

Success Response 200: Campaign updated #

{
  "name": "New Campaign",
  "status": "active",
  "sending_type": "sms",
  "schedule_type": "once",
  "schedule_rrule": "2024-05-01 17:05:00",
  "template": "Hello world",
  "webpush_title": "string",
  "webpush_body": "string",
  "webpush_target_url": "string",
  "webpush_icon": "string",
  "webpush_image": "string",
  "sender": "+41587000000",
  "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618",
  "query_type": "segmentation",
  "query": "{\"segmentation\":[{\"operator\":\"OR\",\"rules\":[{\"field\":\"subscription_options_in\",\"condition\":\"in\",\"value\":[\"7c4c1e07-4c65-4861-ab82-9f8fd9cd3913\",\"94bb60a3-7b4b-4614-913c-0a2760e5f633\"],\"operator\":\"AND\"}]}]}\n",
  "uuid": "string",
  "created_dt": "2024-02-06T14:22:57.274Z",
  "updated_dt": "2024-02-06T14:22:57.274Z",
  "next_dt": "2024-02-06T14:22:57.274Z",
  "last_dt": "2024-02-06T14:22:57.274Z"
}

Error Response 400: Invalid request #

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Error Response 404: Campaign not found #

3.5 Change a Campaign Status #

PATCH/services/{serviceUuid}/campaigns/{campaignUuid}

Changes a campaign Status – toggle active/stopped.

Method Overview #

The method changes a campaign Status – toggle active/stopped.

Example #

Stopping an existing campaign by its UUID and setting a new status.

  curl -X 'PATCH' \
    'https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/campaigns/CAMPAIGN_UUID' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "status": "stopped"
    }'

Parameters #

Name	Type	Description
serviceUuid (required)	string (path)	Service (BM Account) UUID.
campaignUuid (required)	string (path)	Campaign UUID.
body (required)	string (body)	Change campaign Status, stop/resume. Find below CampaignStatus data model description.

Data Parameters #

Change Campaign Status data example

{
  "status": "active"
}

Responses #

Code	Description	Links
200	Campaign status changed.	No links.
400	Invalid request.	No links.
404	Campaign not found.	No links.

Success Response 200: Campaign status changed #

Error Response 400: Invalid request #

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Error Response 404: Campaign not found #

3.6 Delete a Campaign #

DELETE/services/{serviceUuid}/campaigns/{campaignUuid}

Deletes a Campaign.

Method Overview #

The method deletes an existing campaign by its UUID.

Example #

curl -X 'DELETE' \
  'https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/campaigns/CAMPAIGN_UUID' \
  -H 'accept: application/json'

Parameters #

Name	Type	Description
serviceUuid (required)	string (path)	Service (BM Account) UUID.
campaignUuid (required)	string (path)	Campaign UUID.

Responses #

Code	Description	Links
204	Campaign deleted.	No links
404	Campaign not found.	No links

Success Response 204: Campaign deleted #

Error Response 404: Campaign not found #

4. Data Models #

Data Models define the structure of a JSON document and describe the data related to the Campaign API.

4.1 Campaign #

Campaign object properties:

Name	Type	Description
name (required)	string	Campaign Name. Example: New Campaign.
status (required)	string	When creating a campaign it can be either `active` or `draft`. Possible values: active, stopped, finished, draft. Example: active.
sending_type (required)	string	Messaging channel. Possible values: sms, webpush, email, telegram, rbm, viber, whatsapp. Example: sms.
schedule_type (required)	string	Schedule type defines when a campaign is going to be executed, `now` runs as soon as saved, `once` runs once in the defined future time, `scheduled` runs per rrule spec. Possible values: now, once, scheduled. Example: once.
schedule_rrule	string	This field defines how and when the campaign is going to be executed. In the case of schedule_type `once`, this is time in the format `Y-m-d H:i:s` in UTC timezone. For `scheduled`, it’s iCal RRule string to define recurrence. Example: 2024-05-01 17:05:00. More details can be found on iCalendar.org page.
template (required)	string	Campaign messages content. Depending on the `sending_type`, template can be `sms` plan text, or in the case of other channels serialized standardized JSON message format. Example: Hello world. In case of other channels than sms and webpush, Examples of JSON format of template field is presented below. More details about messages data model, can be found in ResponseBody data model description section.
webpush_title	string	Webpush message title.
webpush_body	string	Webpush message content body.
webpush_target_url	string	Webpush message target URL.
webpush_icon	string	Webpush message URL to an icon.
webpush_image	string	Webpush message URL to an image.
sender (required)	string	Campaign messages sender. Depending on the `sending_type`, a sender can be `sms` registered sender ID, `email` email address, `whatsapp` business phone number ID. Example: +41587000000.
recipient_lists (required)	string	One or more (comma separated) list of UUIDs from which the contacts are to be targeted. Example: cf9eeb30-c1af-11ee-8073-bf4d6e8c1618.
query_type	string	If all contacts from a list are to be targeted, use `all`. If you want to apply segmentation by `query` field, set this value to `segmentation`. Possible values: all, segmentation. Example: segmentation.
query	string	This field defines segmentation query applied if query_type is `segmentation`. It is a string as serialized JSON SegmentationQuery data model. An Example of JSON format of query field is presented below.

4.2 CampaignCreate #

CampaignCreate object properties:

Name	Type	Description
name (required)	string	Campaign Name. Example: New Campaign.
status (required)	string	When creating a campaign it can be either `active` or `draft`. Possible values: active, stopped, finished, draft. Example: active.
sending_type (required)	string	Messaging channel. Possible values: sms, webpush, email, telegram, rbm, viber, whatsapp. Example: sms.
schedule_type (required)	string	Schedule type defines when a campaign is going to be executed, `now` runs as soon as saved, `once` runs once in the defined future time, `scheduled` runs per rrule spec. Possible values: now, once, scheduled. Example: once.
schedule_rrule	string	This field defines how and when the campaign is going to be executed. In the case of schedule_type `once`, this is time in the format `Y-m-d H:i:s` in UTC timezone. For `scheduled`, it’s iCal RRule string to define recurrence. Example: 2024-05-01 17:05:00.
template (required)	string	Campaign messages content. Depending on the `sending_type`, template can be `sms` plan text, or in the case of other channels serialized standardized JSON message format. Example: Hello world. In case of other channels than sms and webpush, an Example of JSON format of template field is presented below.
webpush_title	string	Webpush message title.
webpush_body	string	Webpush message content body.
webpush_target_url	string	Webpush message target URL.
webpush_icon	string	Webpush message URL to an icon.
webpush_image	string	Webpush message URL to an image.
sender (required)	string	Campaign messages sender. Depending on the `sending_type`, a sender can be `sms` registered sender ID, `email` email address, `whatsapp` business phone number ID. Example: +41587000000.
recipient_lists (required)	string	One or more (comma separated) list of UUIDs from which the contacts are to be targeted. Example: cf9eeb30-c1af-11ee-8073-bf4d6e8c1618.
query_type	string	If all contacts from a list are to be targeted, use `all`. If you want to apply segmentation by `query` field, set this value to `segmentation`. Possible values: all, segmentation. Example: segmentation.
query	string	This field defines segmentation query applied if query_type is `segmentation`. It is a string as serialized JSON SegmentationQuery data model. An Example of JSON format of query field is presented below.
clone_uuid	string	UUID of a campaign to be cloned from. Example: 1592695e-c1b1-11ee-b153-774c9d3a7957.
template_vars	object	In the case of cloning, here can be provided a map of variable name -> variable value to be replaced in the final campaigns content. Variables in template are to be in the form `{var_name}` but in this map, it’s expected to use raw name, without braces. Example: { “temp”: “-22C”, “wind”: “100km/h” }.

JSON Example #

{
  "name": "New Campaign",
  "status": "active",
  "sending_type": "sms",
  "schedule_type": "once",
  "schedule_rrule": "2024-05-01 17:05:00",
  "template": "Hello world",
  "webpush_title": "string",
  "webpush_body": "string",
  "webpush_target_url": "string",
  "webpush_icon": "string",
  "webpush_image": "string",
  "sender": "+41587000000",
  "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618",
  "query_type": "segmentation",
  "query": "{\"segmentation\":[{\"operator\":\"OR\",\"rules\":[{\"field\":\"subscription_options_in\",\"condition\":\"in\",\"value\":[\"7c4c1e07-4c65-4861-ab82-9f8fd9cd3913\",\"94bb60a3-7b4b-4614-913c-0a2760e5f633\"],\"operator\":\"AND\"}]}]}\n",
  "uuid": "string",
  "created_dt": "2019-08-24T14:15:22Z",
  "updated_dt": "2019-08-24T14:15:22Z",
  "next_dt": "2019-08-24T14:15:22Z",
  "last_dt": "2019-08-24T14:15:22Z"
}

4.3 CampaignUpdate #

CampaignUpdate object properties:

Name	Type	Description
name (required)	string	Campaign Name. Example: New Campaign.
status (required)	string	When creating a campaign, it can be either `active` or `draft`. Possible values: active, stopped, finished, draft. Example: active.
sending_type (required)	string	Messaging channel. Possible values: sms, webpush, email, telegram, rbm, viber, whatsapp. Example: sms.
schedule_type (required)	string	Schedule type defines when a campaign is going to be executed, `now` runs as soon as saved, `once` runs once in the defined future time, `scheduled` runs per rrule spec. Possible values: now, once, scheduled. Example: once.
schedule_rrule	string	This field defines how and when the campaign is going to be executed. In the case of schedule_type `once`, this is time in the format `Y-m-d H:i:s` in UTC timezone. For `scheduled`, it’s iCal RRule string to define recurrence. Example: 2024-05-01 17:05:00.
template (required)	string	Campaign messages content. Depending on the `sending_type`, template can be `sms` plan text, or in the case of other channels serialized standardized JSON message format. Example: Hello world. In case of other channels than sms and webpush, an Example of JSON format of template field is presented below.
webpush_title	string	Webpush message title.
webpush_body	string	Webpush message content body.
webpush_target_url	string	Webpush message target URL.
webpush_icon	string	Webpush message URL to an icon.
webpush_image	string	Webpush message URL to an image.
sender (required)	string	Campaign messages sender. Depending on the `sending_type`, a sender can be `sms` registered sender ID, `email` email address, `whatsapp` business phone number ID. Example: +41587000000.
recipient_lists (required)	string	One or more (comma separated) list of UUIDs from which the contacts are to be targeted. Example: cf9eeb30-c1af-11ee-8073-bf4d6e8c1618.
query_type	string	If all contacts from a list are to be targeted, use `all`. If you want to apply segmentation by `query` field, set this value to `segmentation`. Possible values: all, segmentation. Example: segmentation.
query	string	This field defines segmentation query applied if query_type is `segmentation`. It is a string as serialized JSON SegmentationQuery data model. An Example of JSON format of query field is presented below.

4.4 CampaignResponse #

CampaignResponse object properties:

Name	Type	Description
name (required)	string	Campaign Name. Example: New Campaign.
status (required)	string	When creating a campaign it can be either `active` or `draft`. Possible values: active, stopped, finished, draft. Example: active.
sending_type (required)	string	Messaging channel. Possible values: sms, webpush, email, telegram, rbm, viber, whatsapp. Example: sms.
schedule_type (required)	string	Schedule type defines when a campaign is going to be executed, `now` runs as soon as saved, `once` runs once in the defined future time, `scheduled` runs per rrule spec. Possible values: now, once, scheduled. Example: once.
schedule_rrule	string	This field defines how and when the campaign is going to be executed. In the case of schedule_type `once`, this is time in the format `Y-m-d H:i:s` in UTC timezone. For `scheduled`, it’s iCal RRule string to define recurrence. Example: 2024-05-01 17:05:00.
template (required)	string	Campaign messages content. Depending on the `sending_type`, template can be `sms` plan text, or in the case of other channels serialized standardized JSON message format. Example: Hello world. In case of other channels than sms and webpush, an Example of JSON format of template field is presented below.
webpush_title	string	Webpush message title.
webpush_body	string	Webpush message content body.
webpush_target_url	string	Webpush message target URL.
webpush_icon	string	Webpush message URL to an icon.
webpush_image	string	Webpush message URL to an image.
sender (required)	string	Campaign messages sender. Depending on the `sending_type`, a sender can be `sms` registered sender ID, `email` email address, `whatsapp` business phone number ID. Example: +41587000000.
recipient_lists (required)	string	One or more (comma separated) list of UUIDs from which the contacts are to be targeted. Example: cf9eeb30-c1af-11ee-8073-bf4d6e8c1618.
query_type	string	If all contacts from a list are to be targeted, use `all`. If you want to apply segmentation by `query` field, set this value to `segmentation`. Possible values: all, segmentation. Example: segmentation.
query	string	This field defines segmentation query applied if query_type is `segmentation`. It is a string as serialized JSON SegmentationQuery data model. An Example of JSON format of query field is presented below.
uuid	string	Campaign UUID.
created_dt	string($date‑time)	Campaign’s created time in RFC 3339 format.
updated_dt	string($date‑time)	Campaign’s updated time in RFC 3339 format.
next_dt	string($date‑time)	Campaign’s next execution time in RFC 3339 format.
last_dt	string($date‑time)	Campaign’s last execution time in RFC 3339 format.

JSON Example #

{
  "name": "New Campaign",
  "status": "active",
  "sending_type": "sms",
  "schedule_type": "once",
  "schedule_rrule": "2024-05-01 17:05:00",
  "template": "Hello world",
  "webpush_title": "string",
  "webpush_body": "string",
  "webpush_target_url": "string",
  "webpush_icon": "string",
  "webpush_image": "string",
  "sender": "+41587000000",
  "recipient_lists": "cf9eeb30-c1af-11ee-8073-bf4d6e8c1618",
  "query_type": "segmentation",
  "query": "{\"segmentation\":[{\"operator\":\"OR\",\"rules\":[{\"field\":\"subscription_options_in\",\"condition\":\"in\",\"value\":[\"7c4c1e07-4c65-4861-ab82-9f8fd9cd3913\",\"94bb60a3-7b4b-4614-913c-0a2760e5f633\"],\"operator\":\"AND\"}]}]}\n",
  "uuid": "string",
  "created_dt": "2024-02-05T09:34:11.327Z",
  "updated_dt": "2024-02-05T09:34:11.327Z",
  "next_dt": "2024-02-05T09:34:11.327Z",
  "last_dt": "2024-02-05T09:34:11.327Z"
}

JSON Examples of Message Template Field #

Message template field defines a Campaign messages content. In the case of other channels than sms and webpush, it is serialized standardized JSON message format.

{
  "messages": [
    {
      "body": {
        "textMessage": {
          "content": "Hello John Doe"
        }
      }
    }
  ]
}

{
  "messages": [
    {
      "allowedChannels": [
        "telegram"
      ],
      "body": {
        "cardMessage": {
          "content": {
            "description": "Card message text",
            "media": {
              "url": "https://staging-assets.sms.es.pro/Images/boat.jpg"
            },
            "suggestions": [
              {
                "text": "Visit Us",
                "openUrl": {
                  "url": "https://www.sms.es"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

JSON Example of Message Query Field #

Message query field defines segmentation query applied if query_type is segmentation. It is a string as serialized JSON SegmentationQuery data model.

The example below finds the contacts with first_name John and last_name Smith, or just nick_name is Johnny.

{
  "segmentation": [
    {
      "operator": "OR",
      "rules": [
        {
          "field": "first_name",
          "condition": "eq",
          "value": "John",
          "operator": "AND"
        },
        {
          "field": "last_name",
          "condition": "eq",
          "value": "Smith",
          "operator": "AND"
        }
      ]
    },
    {
      "operator": "OR",
      "rules": [
        {
          "field": "nick_name",
          "condition": "eq",
          "value": "Johnny",
          "operator": "OR"
        }
      ]
    }
  ]
}

4.5 CampaignStatus #

CampaignStatus object properties:

Name	Type	Description
status (required)	string	Campaign status. Possible values: active, stopped.

4.6 CampaignCollection #

CampaignCollection object properties:

Name	Type	Description
data (required)	array	An array of CampaignResponse objects.
meta (required)	object	CollectionMeta object.

4.7 SegmentationQuery #

SegmentationQuery object properties:

Name	Type	Description
segmentation (required)	array	An array of SegmentationGroup objects.

4.8 SegmentationGroup #

SegmentationGroup object properties:

Name	Type	Description
operator (required)	string	A logical operator connecting this group to the previous group. Possible values: OR, AND NOT, OR NOT. Example: OR.
rules (required)	array	An array of SegmentationRule objects.

JSON Example #

{
  "segmentation": [
    {
      "operator": "OR",
      "rules": [
        {
          "field": "first_name",
          "condition": "eq",
          "value": "John",
          "operator": "AND"
        },
        {
          "field": "last_name",
          "condition": "eq",
          "value": "Smith",
          "operator": "AND"
        }
      ]
    },
    {
      "operator": "OR",
      "rules": [
        {
          "field": "nick_name",
          "condition": "eq",
          "value": "Johnny",
          "operator": "OR"
        }
      ]
    }
  ]
}

4.9 SegmentationRule #

SegmentationRule object properties:

Name	Type	Description
field (required)	string	Contact field to be checked. Possible values: first_name, last_name, second_name, nick_name, gender, birthday, salutation, title, language, nationality, mobile, email, phone, address, zip, city, region, country, b_company, b_mobile, b_email, b_phone, b_reception_code, b_address, b_zip, b_city, b_region, b_country, b_job_title, b_department, column_1, column_2, subscription_options_in, subscription_options_out. Example: first_name.
condition (required)	string	Condition to be applied to a field, e.g. comparison. Possible values: eq, neq, isnull, isnotnull, in, notin, startswith, endswith, contains, lt, lte, gt, gte, ann_in_days. Example: eq.
value (required)	string	A string or array of strings to be compared against.
operator (required)	string	A logical operator connection with previous rule, all should be always the same as the first one in this group. Possible values: AND, OR.

4.10 Error #

Error object properties:

Name	Type	Description
code (required)	string	Error code.
message (required)	string	Error message.
description	string	Description.
items	array	An array of ErrorItem objects.

4.11 ErrorItem #

ErrorItem object properties:

Name	Type	Description
name (required)	string	Error item name.
message (required)	string	Error item message.
description	string	Description.

JSON Example #

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

4.12 CollectionMeta #

CollectionMeta object properties:

Name	Type	Description
pagination	object	CollectionMetaPagination object.

4.13 CollectionMetaPagination #

CollectionMetaPagination object properties:

Name	Type	Description
total (required)	integer	Total number of rows.
count (required)	integer	Number of rows in the current page.
perPage (required)	integer	The maximum rows per page.
currentPage (required)	integer	The current page number.
totalPages (required)	integer	Total number of pages.
links (required)	object	CollectionMetaPaginationLinks object.

4.14 CollectionMetaPaginationLinks #

CollectionMetaPaginationLinks object properties:

Name	Type	Description
first	string	Link to the first page.
last	string	Link to the last page.
prev	string	Link to the previous page.
next	string	Link to the next page.

JSON Example #

"meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }

What are your Feelings

Still having problems? How can we help?

Updated on 9 de October de 2025

1. Introduction #

1.1 Overview #

1.2 Getting Credentials #

1.3 Authorization #

1.4 Cloning Existing Campaign #

2. Methods Overview #

3. Methods Details #

3.1 Create or Clone a Campaign #

Method Overview #

Example #

Parameters #

Data Parameters #

Responses #

Success Response 201: New Campaign Response #

Error Response 400: Invalid request #

3.2 Get a List of Campaigns #

Method Overview #

Example #

Parameters #

Responses #

Success Response 200: List of Campaigns #

3.3 Get a Campaign by UUID #

Method Overview #

Example #

Parameters #

Responses #

Success Response 200: Campaign data #

Error Response 404: Resource not found #

Error Response Unexpected Error: Default #

3.4 Update a Campaign #

Method Overview #

Parameters #

Data Parameters #

Responses #

Success Response 200: Campaign updated #

Error Response 400: Invalid request #

Error Response 404: Campaign not found #

3.5 Change a Campaign Status #

Method Overview #

Example #

Parameters #

Data Parameters #

Responses #

Success Response 200: Campaign status changed #

Error Response 400: Invalid request #

Error Response 404: Campaign not found #

3.6 Delete a Campaign #

Method Overview #

Example #

Parameters #

Responses #

Success Response 204: Campaign deleted #

Error Response 404: Campaign not found #

4. Data Models #

4.1 Campaign #

4.2 CampaignCreate #

JSON Example #

4.3 CampaignUpdate #

4.4 CampaignResponse #

JSON Example #

JSON Examples of Message Template Field #

JSON Example of Message Query Field #

4.5 CampaignStatus #

4.6 CampaignCollection #

4.7 SegmentationQuery #

4.8 SegmentationGroup #

JSON Example #

4.9 SegmentationRule #

4.10 Error #

4.11 ErrorItem #

JSON Example #

4.12 CollectionMeta #

4.13 CollectionMetaPagination #

4.14 CollectionMetaPaginationLinks #

JSON Example #

What are your Feelings

Share This Article :

How can we help?