Campaign API v1.0.0

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.Read More
GET/services/{serviceUuid}/campaigns
Gets a list of Campaigns.Read More
GET/services/{serviceUuid}/campaigns/{campaignUuid}
Gets a Campaign by UUID.Read More
PUT/services/{serviceUuid}/campaigns/{campaignUuid}
Updates a Campaign.Read More
PATCH/services/{serviceUuid}/campaigns/{campaignUuid}
Changes a campaign Status - toggle active/stopped.Read More
DELETE/services/{serviceUuid}/campaigns/{campaignUuid}
Deletes a Campaign.Read More

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.Up
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.Up
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.Up
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.Up
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.Up
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.Up
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 RFC3339 format.
updated_dt string($date‑time) Campaign's updated time in RFC3339 format.
next_dt string($date‑time) Campaign's next execution time in RFC3339 format.
last_dt string($date‑time) Campaign's last execution time in RFC3339 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.horisen.pro/Images/boat.jpg"
            },
            "suggestions": [
              {
                "text": "Visit Us",
                "openUrl": {
                  "url": "https://www.horisen.com"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

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"
      }
    }
  }