Introduction
Using the MessageWhiz API, you can create message campaigns, send individual SMS messages or entire message broadcasts, manage recipients, senders, unsubscribers lists, and create and manage templates, tokens and links.
This document will guide you through the core endpoints and functionality of the Message Whiz API, so you can quickly and efficiently start your messaging.
Getting started
In this section, we describe all the necessary steps to send your first broadcast via the MW API.
To start, MessageWhiz uses API keys to allow access to the API. You can find your API key in your personal MW account page.
To properly access the MessageWhiz platform, the API key needs to be included in the header for all API requests to the server.
Sending First Broadcast
In order to send the basic message broadcast, you need to perform the following steps:
- Create a Campaign - a set of SMS messages grouped under one campaign name.
- Create Recipient List - phone numbers to which the messages will be sent.
- Create Sender - a number, name, or ID that recipients see on their devices when they receive a message from you. Only after creating these entities, you can create and send a broadcast. Or you might use already existing entities for broadcasting as well.
Generic replaceable
The following variables should be replaced with your actual information in requests:
Key | Description |
---|---|
<apikey> |
Personal API key |
<url> |
URL from which API is accessed - https://sms.messagewhiz.com/ |
Campaigns
A Campaign unifies a set of SMS messages grouped under one campaign name. The campaign exists in a specified time period, thus start and end dates should be indicated during campaign creation.
Create a Campaign
Example Request
POST /api/3/campaign HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"CampaignName",
"start_date":"2020-07-22T21:00:00.000Z",
"end_date":"2020-09-25T21:00:00.000Z"
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.044941952,
"result": {
"id": 46279,
"is_default": 0,
"name": "CampaignName",
"start_date": "2020-07-22T21:00:00.000Z",
"end_date": "2020-09-25T21:00:00.000Z",
"enabled": true
}
}
Create a Campaign from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/campaign
Request Body
In the request body specify details for the Campaign that will be created.
Required parameters:
name(string)
- Campaign name
Optional parameters:
start_date(string)
- Campaign start date,end_date(string)
- Campaign end date.
Date and time are expressed according to ISO 8601.
Get Campaigns
Request Example
GET /api/3/campaign?start=0 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.012664016,
"result": [
{
"enabled": true,
"id": 46279,
"is_default": 0,
"name": "CampaignName",
"start_date": "2020-07-22T21:00:00.000Z",
"end_date": "2020-09-25T21:00:00.000Z",
"userList": [
{
"campaign_id": 46279,
"user_id": 3191,
"company_id": 3182
}
]
},
{
"enabled": true,
"id": 34641,
"is_default": 1,
"name": "Default campaign",
"start_date": null,
"end_date": null,
"userList": [
{
"campaign_id": 34641,
"user_id": 3191,
"company_id": null
}
]
}
]
}
Get Campaigns from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/campaign
Query Parameters
You can include several parameters in your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active campaigns |
filter |
disabled | filtering by the specific campaign name |
start |
0 | the number of items to skip |
As an example, to get first two inactive campaigns, the query URL will be the following:
GET https://sms.messagewhiz.com/api/3/campaign?limit=2&enabled=false
To get the Campaign by the name:
GET https://sms.messagewhiz.com/api/3/campaign?filter=name=CampaignName
Modify a Campaign
PUT Request Example
PUT /api/3/campaign/46279 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"end_date":"2021-03-25T21:00:00.000Z"
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.026245764,
"result": {
"id": 46279,
"is_default": 0,
"name": "CampaignName",
"start_date": "2020-07-22T21:00:00.000Z",
"end_date": "2021-03-25T21:00:00.000Z",
"enabled": true
}
}
PATCH Request Example
PATCH /api/3/campaign/46279 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"enabled": "1"
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.013305616,
"result": {
"id": 46279,
"enabled": 1
}
}
To modify a specific Campaign from your MessageWhiz account, include its ID in the query:
PUT https://sms.messagewhiz.com/api/3/campaign/{id}
For instance,
PUT https://sms.messagewhiz.com/api/3/campaign/46279
,
where 46279
is the ID of the Campaign that will be replaced using the data presented in the request body.
If you want to partially update the resource, you can use:
PATCH https://sms.messagewhiz.com/api/3/campaign/{id}
Request Body
In the request body specify the value you want to modify, for instance:
{
"end_date":"2021-03-25T21:00:00.000Z"
}
Disable a Campaign
Request Example
DELETE /api/3/campaign/46317 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.034133648,
"result": true
}
To remove a specific Campaign from your MessageWhiz account, add its ID as parameter to the query:
DELETE https://sms.messagewhiz.com/api/3/campaign/{id}
Recipients
Here you can manage your recipients - basically phone numbers grouped into lists of recipients to whom the messages will be sent. Some additional metadata related to each recipient might be included in the recipient lists and used in the broadcasts.
You have two options for the recipient list creation:
- Import .xlsx, .xls, or .csv file with numbers and metadata(optional),
- Add numbers manually in array.
Please make sure to enter the number in the international format, including the country code. For example, enter 18756785619 if you are sending an SMS to a recipient from the USA or Canada, where 1 is the country code.
Create a Recipient List (import a file)
Request Example
curl --location --request POST 'https://sms.messagewhiz.com/api/3/RecipientList?truncate=true' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}' \
--form 'name=FirstRecipientList'
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.032846168,
"result": {
"inserted": 4,
"total": 4,
"wrong": 0,
"duplicate": 0,
"recipient_list_id": 267628
}
}
Create a Recipient List by importing file of contacts:
POST https://sms.messagewhiz.com/api/3/RecipientList?truncate=true
Request Body
In the request body, specify the Recipient List details:
name
- name of the Recipient List.mapping
- the markers to specify the type of stored data in the columns. Possible markers:phone_number
- requiredfirst_name
last_name
email
url
custom
(e.g {"0":"phone_number", "1":"first_name"}
).
The mapping structure should correspond to the structure presented in the uploaded file.
The metadata stored in these marked columns might be used as tokens to send personalized messages.
doc
- an absolute path to the file on your device
(e.g /Users/userName/dir/recipients.csv
).
Query Parameters
Parameter | Default | Description |
---|---|---|
truncate |
false | automatically truncates fields in the list if they are longer than allowed. |
first_name
, last_name
- max length is 50 symbols, email
, url
- 255, other - 5000.
if truncate===false
and there are fields in the list that exceed the limits, an error while loading occurs.
To check if your file fits, you can preview it.
Create a Recipient List (manually)
Request Example
POST /api/3/recipientList/numbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name": "ManuallyAddedList",
"numbers": ["380503327227", "380848122639"]
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.018502512,
"result": {
"inserted": 2,
"wrong": 0,
"duplicate": 0,
"total": 2,
"recipient_list_id": 267888,
"count": 2
}
}
Create a Recipient List by adding the phone numbers manually:
POST https://sms.messagewhiz.com/api/3/recipientList/numbers
Request Body
In the request body, specify the Recipient List details:
name
- name of the created recipient list,numbers
- array of numbers to create a recipient list.
Preview a Recipient List
Request Example
curl --location --request POST 'https://sms.messagewhiz.com/api/3/recipientList/1/preview' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv'
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.00777864,
"result": {
"data": [
[
"phone_number",
"first_name"
],
[
"6593333311",
"Anthony"
],
[
"6593333322",
"Bob"
],
[
"6593333333",
"Jonathan"
],
[
"6593333344",
"Alex"
]
],
"isAllNum": [
true,
false
],
"isExceedLength50": [
false,
false
],
"isExceedLength255": [
false,
false
],
"isExceedLength5000": [
false,
false
]
}
}
MessageWhiz API provides you with the possibility to preview your file of contacts before importing it and creating the Recipient List:
POST https://sms.messagewhiz.com/api/3/recipientList/6/preview
Request Body
In the request body, you should specify:
doc
- an absolute path to the file on your device
Get Recipient Lists
Request Example
GET /api/3/RecipientList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.012814664,
"result": [
{
"id": 267891,
"name": "SecondRecipientList",
"enabled": 1,
"count": 4
},
{
"id": 267888,
"name": "ManuallyAddedList",
"enabled": 1,
"count": 2
},
{
"id": 267628,
"name": "FirstRecipientList",
"enabled": 1,
"count": 4
},
{
"id": 222345,
"name": "ev",
"enabled": 1,
"count": 1
}
]
}
Get Recipient Lists from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/RecipientList
Query Parameters
You can include several parameters in your GET query in order to receive the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active lists |
filter |
disabled | filtering by the specific list name |
start |
0 | the number of items to skip |
For example, to get only the Recipient List with specific name(e.g SecondRecipientList
), use the following query:
https://sms.messagewhiz.com/api/3/RecipientList?filter=name=SecondRecipientList
Get Recipients from Recipient List
Request Example
GET /api/3/recipientList/267628/recipients HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.008162772,
"result": [
{
"phone_number": 6593333311,
"first_name": "Anthony"
},
{
"phone_number": 6593333322,
"first_name": "Bob"
},
{
"phone_number": 6593333333,
"first_name": "Jonathan"
},
{
"phone_number": 6593333344,
"first_name": "Alex"
}
]
}
Get recipients from the specific Recipient List using its ID:
GET https://sms.messagewhiz.com/api/3/recipientList/{id}/recipients
The response contains an object for each recipient in the list,
including their metadata (first_name
, last_name
,email
, url
, custom
).
Get Numbers from Recipient List
Request Example
GET /api/3/recipientList/267628/listNumbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.008841536,
"result": [
"6593333311",
"6593333322",
"6593333333",
"6593333344"
]
}
Get an array of phone numbers from the specific Recipient List using its ID:
GET https://sms.messagewhiz.com/api/3/recipientList/{id}/listNumbers
Download a Recipient List
Request Example
GET /api/3/recipientList/267628/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
"phone_number";"first_name"
"6593333311";"Anthony"
"6593333322";"Bob"
"6593333333";"Jonathan"
"6593333344";"Alex"
Download specific Recipient List using its ID and save the response:
GET https://sms.messagewhiz.com/api/3/recipientList/267628/download
Modify a Recipient List (manually)
PUT Request Example
PUT /api/3/recipientList/267891/numbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name": "Mw-manual",
"numbers": ["380503322227"]
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.019542036,
"result": {
"inserted": 1,
"wrong": 0,
"duplicate": 0,
"total": 1,
"recipient_list_id": 267891,
"count": 5
}
}
PATCH Request Example
PATCH /api/3/RecipientList/267891 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name": "EditingList",
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.031447856,
"result": {
"name": "EditingList",
"enabled": true,
"count": 5
}
}
To modify a specific Recipient List by adding new numbers manually or changing the list name, add its ID to the query:
PUT https://sms.messagewhiz.com/api/3/recipientList/{id}/numbers
In the request body specify the new values for this list:
name(string)
- name of the list, by specifying this value you can change Recipient List name,numbers(array)
- array of numbers that will be added to the list.
If you want to just partially update the resource(by changing the list name), you can use:
PATCH https://sms.messagewhiz.com/api/3/RecipientList/{id}
Modify a Recipient List (import a file)
PUT Request Example
curl --location --request PUT 'https://sms.messagewhiz.com/api/3/recipientList/267891' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/RecipientList.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name", "2":"last_name"}' \
--form 'name=NewList'
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.027778432,
"result": {
"inserted": 4,
"total": 4,
"wrong": 0,
"duplicate": 0,
"recipient_list_id": 267891
}
}
Replace the entire existing Recipient List with the new imported one:
PUT https://sms.messagewhiz.com/api/3/recipientList/{id}
Request Body
In the request body specify the new values for this list:
name
- name of the new recipient list.mapping
- the markers to specify the type of stored data in the columns.
(e.g {"0":"phone_number", "1":"first_name", "2":"last_name"}
).
The mapping structure should correspond to the structure presented in the new uploaded file.
doc
- an absolute path to the file on your device
Disable a Recipient List
Request Example
DELETE /api/3/RecipientList/267891 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.011510284,
"result": true
}
To remove a specific Recipient List from your MessageWhiz account, you should include its ID the query:
DELETE https://sms.messagewhiz.com/api/3/RecipientList/{id}
Senders
Sender is generally a number, name, or ID that recipients see on their devices when they receive a message from you. Here's how to manage a single sender entity.
Create a Sender
Example Request
POST /api/3/sender HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{
"name": "FirstSender"
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.044570548,
"result": {
"id": 28938892,
"name": "FirstSender",
"enabled": true
}
}
Create a Sender from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/sender
Request Body
In the request body only specify a name of the Sender that will be created,
e.g. "name": "FirstSender"
Get Senders
Request Example
GET /api/3/sender? HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.013848856,
"result": [
{
"enabled": true,
"id": 28938892,
"name": "FirstSender"
},
{
"enabled": true,
"id": 28905672,
"name": "test"
}
]
}
Get Senders from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/sender
Query Parameters
You can include several parameters in your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active senders |
filter |
disabled | filter by the specific sender name |
start |
0 | the number of items to skip |
Modify a Sender
PUT Request Example
PUT /api/3/sender/28905672 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name": "TestSender"
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.021960496,
"result": {
"id": 28905672,
"name": "TestSender",
"enabled": true
}
}
To modify a specific Sender from your MessageWhiz account, include its ID in the query:
PUT https://sms.messagewhiz.com/api/3/sender/{id}
Request Body
In the request body specify the new sender name and status for the selected Sender entity, for instance:
{
"name": "TestSender",
"enabled": 0
}
If you want to partially update the resource, you can use:
PATCH https://sms.messagewhiz.com/api/3/sender/{id}
Request Body
In the request body specify the new Sender status, for instance:
{
"enabled": 0
}
Disable a Sender
Request Example
DELETE /api/3/sender/28938891 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.012125844,
"result": true
}
To remove a specific Sender from your MessageWhiz account, you should include its ID to the query:
DELETE https://sms.messagewhiz.com/api/3/sender/{id}
Sender Lists
MessageWhiz provides you with the possibility to group multiple Senders into one Sender List,
from which a Sender will be randomly select for each broadcast message.
Create a Sender List
Example Request
POST /api/3/senderList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{
"name":"FirstSenderList",
"senderIds": [28938892, 28905674]
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.046940544,
"result": {
"id": 5456,
"name": "FirstSenderList",
"enabled": true,
"count": 2
}
}
Create a Sender List from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/senderList
Request Body
In the request body specify the following:
name(string)
- Sender List namesenderIds(array)
- an array of IDs of the Senders that the list will consist of
In case of all invalid senderIds
, Senders will not be added to the list, and the list will be created empty.
Add Senders to a Sender List
Example Request
POST /api/3/senderList/5456/senders HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{
"ids": [28899614, 28899615]
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.032248508,
"result": [
28899614, 28899615
]
}
To add Senders to a Sender List from your MessageWhiz account, specify Sender List ID:
POST https://sms.messagewhiz.com/api/3/senderList/{listId}/senders
Request Body
In the request body specify an array of Sender Ids "ids": [,]
that will be added to the list.
Get Sender Lists
Request Example
GET /api/3/senderList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.00982226,
"result": [
{
"enabled": true,
"id": 5456,
"name": "FirstSenderList",
"count": 2
},
{
"enabled": true,
"id": 5455,
"name": "SenderList",
"count": 1
}
]
}
Get Sender Lists from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/senderList
Query Parameters
You can include several parameters in your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active sender lists |
filter |
disabled | filter by the specific sender list name |
start |
0 | the number of items to skip |
Get Senders from the List
Request Example
GET /api/3/senderList/5456/senders HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.008722612,
"result": {
"id": 5456,
"senders": [
{
"senderId": 28905674,
"name": "test2"
},
{
"senderId": 28938892,
"name": "FirstSender"
}
]
}
}
Get an array of Sender objects from a specific Sender List:
GET https://sms.messagewhiz.com/api/3/senderList/{id}/senders
Modify a Sender List
PUT Request Example
GET /api/3/senderList/5456 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
{
"name": "New",
"senderIds": [28938892, 28905674]
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.040806108,
"result": {
"id": 5456,
"name": "New",
"enabled": true,
"count": 2
}
}
PATCH Request Example
PATCH /api/3/senderList/5456 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"enabled": true,
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.009910892,
"result": {
"id": 5456,
"enabled": 1
}
}
To modify a specific Sender List by adding new Senders and changing the list name, add its ID to the query:
PUT https://sms.messagewhiz.com/api/3/sendertList/{id}
In the request body specify the new values for this list:
name(string)
- name of the list, by specifying this value you can change Sender List name,senderIds(array)
- array of Sender Ids that will be added to the list.enabled(bool)
-true
orfalse
If you want to just partially update the resource(by enabling or disabling it), you can use:
PATCH https://sms.messagewhiz.com/api/3/RecipientList/{id}
Disable a Sender List
Request Example
DELETE /api/3/senderList/5457 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.017833028,
"result": true
}
To remove a specific Sender List from your MessageWhiz account, you should include its ID in the query:
DELETE https://sms.messagewhiz.com/api/3/senderList/{id}
Disable a Sender in the Sender List
Request Example
DELETE /api/3/senderList/5456/senders?id=28905674 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.013993384,
"result": true
}
To remove a Sender from the Sender List, you should include Sender List ID in the query and specify Sender ID as required parameter:
DELETE https://sms.messagewhiz.com/api/3/senderList/{listID}/senders?id={senderID}
Send a Broadcast
Estimate Broadcast
Example Request
POST /api/3/Broadcast/estimate HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"broadcast_type": 11,
"recipient_list_ids": "288696",
"unsubscriber_list_ids": "",
"message_body": "sample"
}
Example Response
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 5.076538867,
"result": {
"messages": 1,
"sum": 3.36,
"parts": 1,
"recipient_id_map": [],
"replacements": {},
"firstSegmentCount": 1,
"recipient_meta_data_map": [
[
3852004823,
{
"phone_number": 3852004823,
"email": "email@gmail.com",
"custom": "Custom",
"url": "https://google.com",
"first_name": "John",
"last_name": "Doe"
}
]
],
"recipients": {
"3852004823": {
"rate": 3.36,
"mccMnc": 111222
}
},
"messageExpanded": {
"actions": {
"callback": {
"replacement": "",
"uuid": "",
"count": 0
},
"first_name": {
"replacement": "",
"count": 0
},
"last_name": {
"replacement": "",
"count": 0
},
"url": {
"replacement": "",
"count": 0
},
"random_symbol": {
"replacement": "h",
"count": 0
},
"verification_code": {
"replacement": "",
"count": 0
},
"custom": {
"replacement": "",
"count": 0,
"parameters": []
},
"custom1": {
"replacement": "",
"count": 0,
"parameters": []
},
"custom2": {
"replacement": "",
"count": 0,
"parameters": []
},
"custom3": {
"replacement": "",
"count": 0,
"parameters": []
},
"custom4": {
"replacement": "",
"count": 0,
"parameters": []
},
"gender": {
"replacement": "",
"count": 0
},
"word_spinner": {
"replacement": "",
"count": 0,
"parameters": [],
"isApproximate": true
},
"link": {
"replacement": "",
"count": 0,
"parameters": []
},
"link_list": {
"replacement": "",
"count": 0,
"parameters": []
},
"unsubscription_link": {
"replacement": "",
"count": 0,
"parameters": []
},
"shorten_url": {
"replacement": "",
"count": 0,
"parameters": []
},
"callback_link": {
"replacement": "",
"count": 0,
"parameters": []
}
},
"text": "sample"
},
"links": {},
"warnings": [],
"estimateHash": "8572aeb3624293a238cd2d7cd901fb61743e3a435e50e00d631a410cb0044d39dd4a53be35e040974f88c7e3799ab1f8d1629455c260a87b0fa48da547c7ffcb",
"batchEstimation": {
"messages": 1,
"sum": 3.36,
"parts": 1
}
}
}
To Estimate a broadcast via API:
POST sms.messagewhiz.com/api/3/Broadcast/estimate
Request Parameters
Required:
recipient_list_ids (string)
- ids of the recipient lists (comma separated numbers)message_body (string)
- body of the message
Optional:
template_id (number)
- id of the message template (may be used instead ofmessage_body
)unsubscriber_list_ids (string)
- ids of the unsubscriber lists (comma separated numbers)recipient (number)
- recipients' number (may be used instead ofrecipient_list_ids
)eb_type (string)
- specifies which type of smart broadcast will be sent (CTR
ormanual
)first_segment_size (number)
- count of the recipients whose messages will be sent within the first (current ifeb_type
ismanual
) segment (available only wheneb_type
is specified)template_ids (string)
- ids of the templates that will be used (available only ifeb_type
is set tomanual
; may be used instead ofmessage_body
; comma separated numbers)next_segment_size (number)
- count of the recipients whose messages will be sent within the next segments of a CTR Threshold broadcast (available only wheneb_type
is set toCTR
)recipient_cap (number)
- count of recipients whose messages will be sent before the broadcast will be paused for further actions (available only wheneb_type
is set toCTR
)
Fast Single
Example Request
POST /sms HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
{
"api_key": <apikey>,
"to": "2605876689",
"from": "sender",
"text": "sample message"
}
Example Response
{
"message_id": "rbzAV2NXxJ_u5bDL35Hop"
}
Example DLR Callback
{
"message_id": "rbzAV2NXxJ_u5bDL35Hop",
"sender": "sender",
"recipient": "5417543010",
"content": "Message Text",
"state": 2,
"status": "DELIVRD",
"client_ref": "Custom param",
"timestamp": "2023-03-28T15:52:31.279Z",
"parts_count": 1,
"price": 2,
"parts": [
{
"pdu_id": "SVV7oRyvMLX1OIzLwta2p",
"encoding": 0,
"content": "Message Text",
"status": "DELIVRD"
}
]
}
Example link click Callback
{
"message_id": "4iE_yS65Vn8iXCqaW5L2N",
"link_id": "hkzt.me/ZPFuT5",
"time": "2023-05-01T13:46:37.921Z",
"unique_click": true
}
Error codes/Validation errors:
without mandatory field "text":
{
"statusCode": 400,
"message": [
"text must be shorter than or equal to 100000 characters",
"text must be longer than or equal to 1 characters",
"text should not be empty"
],
"error": "Bad Request"
}
without mandatory field "to":
{
"statusCode": 400,
"message": [
"The recipient number entered is invalid. Please ensure that the number is between 10 and 15 digits in length."
],
"error": "Bad Request"
}
without mandatory field "from":
{
"statusCode": 400,
"message": [
"Sender must not exceed 11 letters (latin alphabet or special symbols “'._-+&{space}” are allowed) or 20 numbers."
],
"error": "Bad Request"
}
without mandatory field "api_key":
{
"statusCode": 401,
"message": "Unauthorized"
}
To send a single message from your MessageWhiz account:
POST https://sms.messagewhiz.com/sms
Request Body
Required parameters:
api_key
- an API key of your accountfrom
- provide here the Sender nameto
- phone number of the recipienttext
- text of the message that the recipient will see; can contain text and links.
Optional parameters:
client_ref
- custom parameter up to 160 characters, will be present in response for Single creation, DLR to Webhook and callbackcallback
- the URL of callback to which DLR statuses per single message will be sent
Initial HTTP Response
message_id
- the ID of the message
Response on DLR callback
When a single message was sent, we got a response with information about the sent message and DLR status.
Parameters:
message_id
- the ID of the messagesender
- the Sender name that was used in messagerecipient
- phone number of the recipientcontent
- text of the message that the recipient receivedstate
- the id of DLR status of messagestatus
- the DLR status of single message. Possible DLR statuses (with their ids):- 1 -
ENROUTE
- 2 -
DELIVRD
- 3 -
EXPIRED
- 4 -
DELETED
- 5 -
UNDELIV
- 6 -
ACCEPTD
- 7 -
UNKNOWN
- 8 -
REJECTD
- 9 -
FAILED
- 1 -
client_ref
- custom parameter up to 160 characters, will be present in response for Single creation, DLR to Webhook and callbacktimestamp
- time of sending messageparts_count
- the amount of PDUs in the messageprice
- the cost of single messageparts
- information about every PDU, may have such fields:pdu_id
- ID of the message partencoding
- text encoding used for the message partcontent
- text of the message partstatus
DLR status code for the message part
Response on link click callback
After the user’s click on the link, an additional response with the click info appears.
Parameters:
message_id
- the ID of the messagelink_id
- the link that was assigned and clicked by the userunique_click
- identifies that this is a unique clicktime
- time of clicking the link
Send a Tiny single (OLD)
Example Request
POST /api/3/Broadcast/tiny/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"recipient": "2605876689",
"sender": "sender",
"message_body": "sample message"
}
Example Response (200)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.049512918,
"result": {
"broadcastId": 1174181,
"segmentId": 523940
}
}
To send a tiny single message from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/Broadcast/tiny/
Request Body
In the request body, the following single message components can be used.
Required parameters:
recipient (string)
- phone number of the Recipient,sender (string)
- name of the Sender,message_body
- text of the message that recipient will see; can contain only text.
Send a Single message (OLD)
Example Request
POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"Single SMS to 380681337228",
"campaign_id":1,
"broadcast_type":10,
"unsubscriber_list_ids":"",
"sender_id":"23",
"recipient":"380681337228",
"message_body":"message body",
"custom_parameter":"1234abcd5678efgh"
}
Example Response (200 OK)
{
"errorCode":0,
"errorMessage":"",
"errorType":"",
"executionTime":0.160202353,
"result": {
"broadcastID":331,
"segmentID":493,
"custom_parameter":"1234abcd5678efgh"
}
}
To send a single message from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/Broadcast
Request Body
In the request body, the following single message components can be used.
Required parameters:
campaign_id
- an ID of a previously created active Campaign,broadcast_type (int)
- type of the broadcast, for single type the value is10
(10 - single, 11 - base, 12 - smart),recipient (string)
- phone number of the recipient,sender_id(int)
- ID of a previously created Sender.message_body
- text of the message that the recipient will see; can contain text, links, and tokens.
Optional parameters:
unsubscriber_list_ids (string)
- IDs of previously created Unsubscribe Lists,send_date (string)
- specific date and time for sending a message (e.g."2020-07-31T14:25:49.614Z"
),utc_offset
- specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is0
),trigger_id
- id of the trigger,delay
- the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,template_id
- id of the message template, if you want to use a specific template for message body,custom_parameter
- custom parameter up to 40 characters, will be present in responce for Single creation and DLR to Webhook
Send a Base Broadcast
Example Request
POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"broadcast",
"campaign_id":1,
"broadcast_type":11,
"unsubscriber_list_ids":"",
"sender_ids":"23",
"recipient_list_ids":"12",
"message_body":"broadcast message",
}
Example Response (200 OK)
{
"errorCode":0,
"errorMessage":"",
"errorType":"",
"executionTime":0.446636071,
"result": {
"broadcastID":333,
"segmentID":494
}
}
To send a Basic Broadcast from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/Broadcast
Request Body
In the request body, the following broadcast components can be used.
Required parameters:
campaign_id
- an ID of a previously created active Campaign,broadcast_type
- type of broadcast, for base broadcast type the value is11
(10 - single, 11 - base, 12 - smart),name
- broadcast name,sender_ids (string)
- IDs of previously created Senders,recipient_list_ids (string)
- IDs of previously created Recipient Lists,message_body
- text of the message that the recipient will see; can contain text, links, and tokens.
Optional parameters:
sender_list_ids (string)
- IDs of previously created Sender Lists,unsubscriber_list_ids (string)
- IDs of previously created Unsubscribe Lists,send_date (string)
- specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z"
),utc_offset (int)
- specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is0
),trigger_id
- id of the trigger,delay
- the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,template_id
- id of the message template, if you want to use a specific template for message body.
Send a Smart Broadcast
Example Request
POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"manual",
"campaign_id":1,
"broadcast_type":12,
"unsubscriber_list_ids":"",
"sender_ids":"23",
"recipient_list_ids":"12",
"message_body":"man message",
"send_date":"2021-03-01T12:41:38.837Z",
"utc_offset":120,
"eb_type":"manual",
"first_segment_size":"3",
}
Example Response (200 OK)
{
"errorCode":0,
"errorMessage":"",
"errorType":"",
"executionTime":0.446636071,
"result": {
"broadcastID":333,
"segmentID":495
}
}
To send a Smart Broadcast from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/Broadcast
In the request body, the following broadcast components can be used.
Required parameters:
campaign_id
- an ID of a previously created active Campaign,broadcast_type
- type of broadcast, for smart broadcast type the value is12
(10 - single, 11 - base, 12 - smart),name
- broadcast name,eb_type (sting)
- type of smart broadcast, can be either 'CTR' or 'manual',sender_ids (string)
- IDs of previously created Senders,recipient_list_ids(string)
- IDs of previously created Recipient Lists,message_body
- text of the message that the recipient will see; can contain text, links, and tokens.
To send the Manual Smart Broadcast add the following parameters.
Required parameters:
first_segment_size (int)
- the size of the segment
Optional parameters:
sender_list_ids (string)
- IDs of previously created Sender Lists,unsubscriber_list_ids(string)
- IDs of previously created Unsubscribe Lists,send_date(string)
- specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z"
),utc_offset
- specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is0
),trigger_id
- id of the trigger,delay
- the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,template_id
- id of the message template, if you want to use a specific template for message body,template_ids(string)
- IDs of the message templates, if you want to use a specific templates for message body,
To send the CTR Threshold Smart Broadcast add the following parameters.
Required parameters:
exp_date (date)
- the date when the broadcasts will expire (e.g."2021-09-25 13:55:58"
),conversion_threshold (int)
- upon reaching this conversion rate, the next segment will be sent (e.g. value50
means 50% conversion)first_segment_size (int)
- the size of the first segment (for 'CTR' type),next_segment_size (int)
- the size of the next segments in CTR broadcast (for 'CTR' type),recipeint_cap (int/string)
- either the number of recipients to limit the broadcast sending (should be greater than 2), or string"no limit"
(for 'CTR' type).
Optional parameters:
sender_list_ids (string)
- IDs of previously created Sender Lists,unsubscriber_list_ids(string)
- IDs of previously created Unsubscribe Lists,send_date(string)
- specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z"
),utc_offset
- specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is0
),trigger_id
- id of the trigger,delay
- the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,template_id
- id of the message template, if you want to use a specific template for message body,
Continue smart broadcast
Example Request
POST /api/3/Segments HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"broadcast_id": 111
"message_body": "sample"
"segment_size": 1
"send_now": true
"sender_ids": "1"
"utc_offset": 180
}
Example Response
{
"errorCode":0,
"errorMessage":"",
"errorType":"",
"executionTime":2.202010018,
"result":{
"real_price":0,
"id":1,
"broadcast_id":111,
"utc_offset":180,
"message_body":"sample",
"template_id":null,
"batch_index":null,
"state":0,
"recipient_count":1,
"estimated_price":3.36,
"send_conditions_id":1,
"enabled":true,
"created_at":"2021-06-25 14:02:50",
"send_time":"2021-06-25 14:02:50",
"estimated_count":1
}
}
To continue a smart broadcast:
POST sms.messagewhiz.com/api/3/Segments
Request Parameters
Required:
broadcast_id (number)
- id of the broadcast to be continuedmessage_body (string)
- message for the segmentsegment_size (number)
- count of the recipients whose messages will be sent within the segmentsender_ids
- ids of the senders which will be used for the created segmentsend_now
- specifies if the segment should be sent as soon as possible
Optional:
template_ids
- ids of the templates that will be used for the created segment (may be used instead ofmessage_body
)sender_list_ids
- ids of the sender lists which will be used for the created segment (may be used instead ofsender_ids
)trigger_id
- id of the trigger that will be used to send the segment (may be used instead ofsend_now
)send_date
- date when the segment will be send (may be used instead ofsend_now
)utc_offset
- specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is0
)recipient_cap
- count of recipients whose messages will be sent before the broadcast will be paused for further actions (should be specified if a paused CTR Threshold broadcast is being continued)first_segment_size
- count of the recipients whose messages will be sent within the first segment of the batch (should be specified if a paused CTR Threshold broadcast is being continued)next_segment_size
- count of the recipients whose messages will be sent within the next segments of the batch (should be specified if a paused CTR Threshold broadcast is being continued)
Send One time password (OTP)
Example Request
POST /api/broadcasts/single?otp=true HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"campaign_id": 1,
"sender_id": "23",
"message_body": "verification code: {{verification_code}}",
"send_date": "2021-03-01T12:41:38.837Z",
"utc_offset": 120,
"recipient": "2605876689",
"verification": true
}
Example Response (200 OK)
{
"id": 123
}
To send a single sms with an OTP from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/broadcasts/single?otp=true
Request Body
You can pass such parameters in the request body
Required parameters:
campaign_id (integer)
- an ID of a previously created active Campaign,message_body
- text of the message that the recipient will see ({{verification_code}}
token is required).sender_id (string)
- ID of a previously created Sender,recipient (string)
- phone number of the Recipient,verification (boolean)
- indicates if the message should contain an OTP (should be true)
Optional parameters:
message_template_id (integer)
- id of the message template (it should contain{{verification_code}}
token, passed instead ofmessage_body
)sender (string)
- name of the Sender (passed instead ofsender_id
)unsubscriber_list_ids (string)
- IDs of previously created Unsubscribe Listsutc_offset (integer)
- specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is0
)is_now (bool)
- starting condition for the broadcastsend_date (Date)
- specific date and time for sending the broadcast (ifis_now: false
)trigger_id (integer)
- id of the trigger (ifis_now: false
)
Verify OTP
Example Request
POST /api/recipients/{phone_number}/verification HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"verification_code": 2253
}
Example Response (200 OK)
{
"valid": true
}
To verify an OTP which was sent earlier:
POST https://sms.messagewhiz.com/api/recipients/{phone_number}/verification
Where {phone_number} should be substituted with the phone number of the recipient to whom the OTP has been sent.
Request Body
Only one parameter should be passed in the request body:
verification_code
- the verification code that was sent to the recipient
Get Broadcasts List
Example Request
GET /api/3/Broadcast/List HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
Example Response
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.351626371,
"result": [
{
"id": 200,
"user_id": 123,
"name": "sample broadcast",
"type": 1,
"message_body": "sample message",
"enabled": 1,
"trigger_id": null,
"send_date": "2041-03-07T11:41:55.000Z",
"state": 2,
"parent_id": null,
"real_price": 0,
"estimated_price": 10.50,
"create_date": "2019-08-05T13:20:04.000Z",
"estimated_count": 8,
"utc_offset": 0,
"next_segment_size": null,
"eb_type": null,
"company_name": "sample company",
"timezone": "GMT +0",
"send_now": false,
"broadcastConversion": {
"uniqueClicks": 0,
"totalClicks": 0,
"recipientCount": 8,
"conversion": "0.00",
"broadcastId": 200
}
}
]
}
Get Broadcasts from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/Broadcast/List
Query Parameters
You can include several parameters to your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
start |
0 | the number of items to skip |
filter |
disabled | filtering by the specific broadcast field |
orderby |
create_date DESC | criteria and order by which the broadcasts will be sorted |
Parameters possible values
Limit
- numbers in range 1-100start
- any integersorderby
- Has two values separated by a space (i.g. create_date DESC).
First value is the field by which results will be ordered. May besend_date
orcreate_date
.
Second value is the order itself. May beASC
orDESC
which stands for ascending and descending, respectively.filter
- Filter has a specific format:
?filter={parameter_name}={parameter_value},{parameter_name}...
Available parameters are:
name
- pattern for the broadcast name (the actual name will contain the given string)type
- type of the broadcast0
- previous approach singe1
- previous approach basic broadcast2
- previous approach smart broadcast3
- previous approach child broadcast (part of a smart)10
- single broadcast11
- basic broadcast12
- smart broadcast
parent_id
- parent_id of the broadcast (type is automatically set to 3)start_date
- start of the date range by which to filterend_date
- end of the date range by which to filterfilterBy
- determines by which date broadcasts will be filtered (create date
orsend date
)create_date
- filters by the date of broadcast creationsend_date
- filters by the broadcasts send date
For example filter with such format:
?filter=name=sample,type=2,type=12,filterBy=create_date,start_date=06/01/2021 12:00 AM
Will find all the smart broadcasts (both approaches) that was created later than 06/01/2021 12:00 AM which name contains sample substring
Single request broadcasts
Example Request
POST /api/3/Broadcast/combinedsubmit HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"message_body": "hello {{first_name}} {{last_name}} here is {{custom2}} click on link {{shorten_url}}!!",
"sender": "My sender",
"recipients": [
{
"phone_number": 380100001010,
“first_name": "John",
"last_name": "Doe",
"custom2": "MyCustomToken",
"url": "https://mylink1.com"
},
{
"phone_number": 380100001011,
"first_name": "Bob",
"url": "https://mylink2.com"
}
]
}
Example Response
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.351626371,
"result": [
{
"broadcastID":333,
"segmentID":495
}
]
}
An endpoint on Segment Based architecture which enables creating a Base Broadcast and sending it to a new Recipient list withone request.
Request parameters
Required
recipients
- json file with all needed data (phone number, first name, last name, URL ect. per each recipient)sender
orsender_id
- an ID of previously created sender or a value.message_body (string)
- text of the message that the recipient will see; can contain text, links, and tokens.
Optional
name (string)
- The name of broadcast is an optional parameter. If it is defined in the request, this value will be used as the name. If it is not provided, the broadcast ID will be used as a namesend_date (Date)
- it can be added to request and the broadcast will be scheduled for the defined date, if not - the broadcast will be sent immediately
Unsubscribe Lists
Unsubscribe lists - lists of numbers that will be excluded from recipient lists and will not receive messages from you. An unsubscribe list consists of the numbers that opted out of your broadcasts as well as numbers you added to the list yourself.
Create a Unsubscribe List (import a file)
Request Example
curl --location --request POST 'https://sms.messagewhiz.com/api/3/UnsubscribeList?truncate=true' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}' \
--form 'name=FirstRecipientList'
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.032846168,
"result": {
"enabled": true,
"id": 123,
"name": "FirstRecipientList",
"company_id": 1,
"unsubscribers_amount": 10,
"user_id": 1
}
}
Create an Unsubscribe List by importing file of contacts:
POST https://sms.messagewhiz.com/api/3/UnsubscribeList?truncate=true
Request Body
In the request body, specify the Unsubscribe List details:
name
- name of the Unsubscribe List.mapping
- the markers to specify the type of stored data in the columns. Possible markers:phone_number
- requiredfirst_name
last_name
email
url
custom
(e.g {"0":"phone_number", "1":"first_name"}
).
The mapping structure should correspond to the structure presented in the uploaded file.
The metadata stored in these marked columns might be used as tokens to send personalized messages.
doc
- an absolute path to the file on your device
(e.g /Users/userName/dir/unsubscribers.csv
).
Query Parameters
Parameter | Default | Description |
---|---|---|
truncate |
false | automatically truncates fields in the list if they are longer than allowed. |
first_name
, last_name
- max length is 50 symbols, email
, url
- 255, other - 5000.
if truncate===false
and there are fields in the list that exceed the limits, an error while loading occurs.
To check if your file fits, you can preview it.
Create an Unsubscribe List (manually)
Example Request
POST /api/3/unsubscribeList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{
"name":"FirstUnsubscribeList",
"numbers": [380502222233]
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.025868544,
"result": {
"enabled": true,
"id": 21534,
"name": "FirstUnsubscribeList",
"company_id": 3182,
"unsubscribers_amount": 1,
"user_id": 3191
}
}
Create an Unsubscribe List from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/unsubscribeList
Request Body
In the request body specify the following:
name(string)
- Unsubscribe List namenumbers(array)
- an array of phone numbers that the Unsubscribe List will consist of
Preview an Unsubscribe List
Request Example
curl --location --request POST 'https://sms.messagewhiz.com/api/3/unsubscribeList/preview/4' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv'
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.008022008,
"result": {
"data": [
[
"phone_number"
],
[
"6593333311"
],
[
"6593333322"
],
[
"6593333333"
],
[
"6593333344"
]
],
"isAllNum": [
true,
true,
true,
true
],
"isExceedLength50": [
false,
false,
false,
false
],
"isExceedLength255": [
false,
false,
false,
false
],
"isExceedLength5000": [
false,
false,
false,
false
]
}
}
MessageWhiz API provides you with the possibility to preview your file of contacts before actually importing it and to create the Unsubscribe List:
POST https://sms.messagewhiz.com/api/3/unsubscribeList/preview
Request Body
In the request body, you should specify:
doc
- an absolute path to the file on your device
Add Numbers to Unsubscribe List
Example Request
POST /api/3/UnsubscribeList/21534/members HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{
"numbers":["380502222233", "380643333322"]
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.031270908,
"result": {
"inserted": 2,
"alreadyExists": 0,
"notValid": 0
}
}
Add phone numbers to the existing Unsubscribe List (include its ID in the query):
POST https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/members
Request Body
In the request body specify:
numbers(array)
- an array of phone numbers that will be added to the Unsubscribe List
Get Unsubscribe Lists
Request Example
GET /api/3/unsubscribeList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.028108664,
"result": [
{
"id": 21534,
"name": "FirstUnsubscribeList",
"enabled": 1,
"unsubscribers_amount": 3
}
]
}
Get Unsubscribe Lists from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/unsubscribeList
Query Parameters
You can include several parameters to your GET query in order to receive the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active lists |
filter |
disabled | filtering by the specific list name |
start |
0 | the number of items to skip |
For example, to get only an Unsubscribe List with a specific name(e.g FirstUnsubscribeList
), use the following query:
https://sms.messagewhiz.com/api/3/RecipientList?filter=name=FirstUnsubscribeList
Get Numbers from Unsubscribe List
Request Example
GET /api/3/unsubscribeList/21534/members HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.018904092,
"result": [
{
"phone_number": "380643333322"
},
{
"phone_number": "380502327265"
},
{
"phone_number": "380502222233"
}
]
}
Get phone numbers from the specific Unsubscribe List using its ID:
GET https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/members
Download an Unsubscribe List
Request Example
GET /api/3/unsubscribeList/21534/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
"phone_number"
"380502327265"
"380502222233"
"380643333322"
Download a specific Unsubscribe List using its ID and then save the response:
GET https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/download
Modify an Unsubscribe List (import a file)
PUT Request Example
curl --location --request PUT 'https://sms.messagewhiz.com/api/3/UnsubscribeList/21534' \
--header 'apikey: <apikey>' \
--form 'mapping={"0":"phone_number"}' \
--form 'doc=@/home/user/Downloads/UnsubscribeList.csv'
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.040112328,
"result": {
"enabled": true,
"id": 21534,
"name": "FirstUnsubscribeList",
"company_id": 3182,
"unsubscribers_amount": 4,
"user_id": 3191
}
}
PATCH Request Example
PATCH /api/3/UnsubscribeList/21534 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"enabled": false
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.022112432,
"result": {
"id": 21534,
"enabled": false
}
}
Replace the entire existing Unsubscribe List with the new imported one:
PUT https://sms.messagewhiz.com/api/3/UnsubscribeList/{id}
Request Body
In the request body specify the new values for this list:
mapping
- the markers to specify the type of stored data above each column.
(e.g {"0":"phone_number"}
).
The mapping structure should correspond to the structure presented in the new uploaded file.
doc
- an absolute path to the file on your device.
If you want to partially update the resource, you can use:
PATCH https://sms.messagewhiz.com/api/3/UnsubscribeList/{id}
You can disable an unsubscribe list by entering "enabled": false
in the request body.
Disable an Unsubscribe List
Request Example
DELETE /api/3/UnsubscribeList/21567 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.01279094,
"result": true
}
To remove a specific Unsubscribe List from your MessageWhiz account, you should include its ID in the query:
DELETE https://sms.messagewhiz.com/api/3/unsubscribeList/{id}
Links
MessageWhiz provides you with the possibility to include Links in your message broadcasts.
You are able to create and manage Links beforehand, and then just insert them in a message as a Link token({{link:linkId}}
).
Create a Link
Example Request
POST /api/3/link HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"Link1",
"url": "https://foot1.com"
"platform_based_links": {
"bot_redirect":"https://foot32.com/desktop"
"preview_url":"https://foot12.com"
}
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.01954006,
"result": {
"id": 165655,
"name": "Link1",
"url": "https://foot1.com",
"enabled": true,
"type":0,
"platform_based_links": {
"bot_redirect":"https://foot32.com/desktop",
"preview_url":"https://foot12.com"
}
}
}
Create a Link from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/link
Request Body
In the request body specify details for the Link that will be created.
Required parameters:
name(string)
- Link name,url
- Link url itself, in the URI format
Optional parameters:
platform_based_links
- object that has two properties:"bot_redirect"
- the recipients who click the link from the PC, will be redirected to this link"preview_url"
- will be used to show the preview of your main link
Get Links
Request Example
GET /api/3/link? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.006230324,
"result": [
{
"enabled": true,
"id": 165655,
"name": "Link1",
"url": "https://foot1.com"
},
{
"enabled": true,
"id": 146746,
"name": "test",
"url": "https://sms.messagewhiz.com/app/workspace/links"
}
]
}
Get Links from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/link
Query Parameters
You can include several parameters to your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active links |
filter |
disabled | filtering by the specific link name/url |
start |
0 | the number of items to skip |
For example, to get only a Link with specific URL (e.g https://foot1.com
), use the following query:
https://sms.messagewhiz.com/api/3/link?filter=url=https://foot1.com
,
or to get a Link by name:
https://sms.messagewhiz.com/api/3/link?filter=name=Link1
Modify a Link
PUT Request Example
PUT /api/3/link/165655 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name": "FirstLink",
"url": "https://foot1.com",
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.011805652,
"result": {
"id": 165655,
"name": "FirstLink",
"url": "https://foot1.com",
"enabled": true
}
}
To modify a specific Link, you should specify its ID in the query:
PUT https://sms.messagewhiz.com/api/3/link/{id}
Request Body
In the request body specify the key and value you want to modify, for example:
{
"name": "FirstLink"
}
The same parameters as for the link creation can be used.
Disable a Link
Request Example
DELETE /api/3/link/165655 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.016383932,
"result": true
}
To remove a specific Link, you should include its ID in the query:
DELETE https://sms.messagewhiz.com/api/3/link/{id}
Monitor link conversion
Example Request
POST /api/3/details/linkConversion HTTP/1.1
Host: sms.messagewhiz.com
apiley: <apikey>
Content-Type: application/json
{
"url":"mmdsmart.com"
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.12326038,
"result": {
"conversion": 100,
"totalRecipients": 1,
"clicks": 1
}
}
To receive conversion data from a certain link:
POST https://sms.messagewhiz.com/api/3/details/linkConversion
Request Body
Only one parameter should be included within the request body:
url
- the link for which you want to monitor conversion
Response Explanation
In the response you can receive 3 main parameters:
Conversion
- level of CTRTotal Recipients
- amount of recipients to which such link was sendClicks
- amount of unique clicks on the link
Link Lists
MessageWhiz provides you with the possibility to group multiple links into one list.
With the help of the Link List token, links from the list will be evenly distributed between recipients of the broadcast.
Just insert Link List in a message as a token({{link_list:linkListId}}
).
Create a Link List
Example Request
POST /api/3/LinkList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{
"name":"FirstLinkList",
"linkIds":["311"]}
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.017949384,
"result": {
"id": 6940,
"name": "FirstLinkList",
"enabled": true,
"linkListLength": 1,
"warning":""
}
}
Create an empty Link List from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/LinkList
Request Body
In the request body specify the name(string)
of the Link List that will be created.
Either
linkIds
- an array of IDs of the previously created Links that the list will contain, or
links
- an array of objects with url and name properties
Example Request
POST /api/3/LinkList/6940/links HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{
"ids":["146746", "13298"]
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.04211898,
"result": [
146746
]
}
To add existing Links to the Link List, include Link List ID in the query:
POST https://sms.messagewhiz.com/api/3/LinkList/{id}/links
Request Body
In the request body specify the "ids(array)"
an array of IDs of the previously created Links that the list will contain.
Or specify one link "id(int)""
.
Create a Link List (import a file)
Request Example
curl --location --request POST 'https://sms.messagewhiz.com/api/3/LinkList' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/linkList.csv' \
--form 'mapping={"0":"name", "1":"url"}' \
--form 'name=FirstLinkList'
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.105039176,
"result": {
"id": 7077,
"name": "FirstLinkList",
"enabled": true
}
}
Create a Link List by importing the file:
POST https://sms.messagewhiz.com/api/3/LinkList
Request Body
In the request body, specify the Link List details:
name
- name of the Link List.mapping
- the markers to specify the type of stored data in the columns:0
: may have property ("name"
or"url"
),1
: may have property ("name"
or"url"
),
The mapping structure should correspond to the structure presented in the uploaded file.
doc
- an absolute path to the file on your device
(e.g /Users/userName/dir/linkList.csv
).
Add New Links to a Link List (Bulk)
Example Request
POST /api/3/LinkList/6940/links/bulk HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
{"links":
[{"name": "some3 name", "url": "https://43.url.com"}, {"name": "some3 name 2", "url": "https://24422.url.com"}]
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.064860264,
"result": {
"enabled": true,
"id": 6940,
"name": "FirstLinkList",
"user_id": 3191,
"company_id": 3182
}
}
To add multiple new Links to the Link List, you should include Link List ID in the query:
POST https://sms.messagewhiz.com/api/3/LinkList/{id}/links/bulk
Request Body
In the request body specify:
links(array)
- an array of Link objects. Link object should consist of the two required attributes -"name"
and"url"
.
Get Link Lists
Request Example
GET /api/3/LinkList? HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.056359856,
"result": [
{
"id": 6943,
"name": "LinksList",
"enabled": 1,
"conversionCount": 0
}
]
}
Get Link Lists from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/LinkList
Query Parameters
You can include several parameters to your GET query in order to receive the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active lists |
filter |
disabled | filtering by the specific list name |
start |
0 | the number of items to skip |
Get Links from the List
Request Example
GET /api/3/LinkList/6941/links HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.010940972,
"result": [
{
"id": 6941,
"links": [
{
"linkId": 146746,
"url": "https://google.com"
},
{
"linkId": 146747,
"url": "https://youtube.com"
}
]
}
]
}
Get an array of Links from a specific Link List by ID:
GET https://sms.messagewhiz.com/api/3/LinkList/{id}/links
Modify a Link List (import a file)
PUT Request Example
curl --location --request PUT 'https://sms.messagewhiz.com/api/3/LinkList/6941' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/SecondLinkList.csv' \
--form 'mapping={"0":"name", "1":"url"}' \
--form 'name=NewList'
PATCH Request Example
PATCH /api/3/LinkList/6944 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"enabled": 1
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.009358444,
"result": {
"id": 6944,
"enabled": 1
}
}
If you want to partially update the resource, you can use:
PATCH https://sms.messagewhiz.com/api/3/linkList/{id}
Disable a Link List
Request Example
DELETE /api/3/LinkList/6941 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 2.519399016,
"result": true
}
Remove a specific Link List from your MessageWhiz account by ID:
DELETE https://sms.messagewhiz.com/api/3/LinkList/{id}
Disable a Link in the Link List
Request Example
DELETE /api/3/LinkList/6940/links?[id]=146746 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.014643696,
"result": true
}
To remove a Link from the Link List, include Link List ID in the query and specify Link ID as required parameter:
DELETE https://sms.messagewhiz.com/api/3/LinkList/{listID}/links?[id]={linkID}
Word Spinners
Word spinner is a token which enables randomizing the text in broadcast messages by randomly selecting from a predefined
list of synonyms, so that the overall message and meaning are left intact while the wording is changed slightly.
Just insert Word Spinner in a message as a token({{word_spinner:ID}}
).
Create a Word Spinner
Example Request
POST /api/3/spinner HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"Fit32",
"words": ["wo", "three", "spinner", "greeetinnngsss", "four", "test", "one", "five"]
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.041090464,
"result": {
"name": "Fit32",
"words": [
"wo",
"three",
"spinner",
"greeetinnngsss",
"four",
"test",
"one",
"five"
],
"enabled": true,
"id": 10520
}
}
Create a Word Spinner from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/spinner
Request Body
In the request body specify details for the Word Spinner that will be created:
name(string)
- Word Spinner name,words(array)
- an array of word synonyms.
Get Word Spinners
Request Example
GET /api/3/spinner? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.018632456,
"result": [
{
"words": [
"wo",
"three",
"spinner",
"greeetinnngsss",
"four",
"test",
"one",
"five"
],
"enabled": true,
"id": 10520,
"name": "Fit32"
}
]
}
Get Word Spinners from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/spinner
Query Parameters
You can include several parameters to your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active spinners |
filter |
disabled | filtering by the specific spinner name |
start |
0 | the number of items to skip |
Modify a Word Spinner
PUT Request Example
PUT /api/3/spinner/10519 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"FirstSpinner"
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.014242532,
"result": {
"name": "FirstSpinner",
"words": [
"wo",
"three",
"spinner",
"greeetinnngsss",
"four",
"test",
"one",
"five"
],
"enabled": true,
"id": 10520
}
}
PATCH Request Example
PATCH /api/3/spinner/10520? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"enabled": "0"
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.0242746,
"result": {
"enabled": 0
}
}
To modify a specific Word Spinner, include its ID in the query:
PUT https://sms.messagewhiz.com/api/3/spinner/{id}
If you want to partially update the resource, you can use:
PATCH https://sms.messagewhiz.com/api/3/spinner/{id}
Request Body
In the request body specify the value you want to modify, for instance:
{
"name":"FirstSpinner"
}
If the name
array is specified in the request body for a PUT request, the previous words will be overwritten.
The Word Spinner might be disabled, by specifying it in the request body for a PATCH request:
{
"enabled": "0"
}
Disable a Word Spinner
Request Example
DELETE /api/3/spinner/10520 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.00986104,
"result": true
}
To remove a specific Word Spinner from your MessageWhiz account, include its ID in the query:
DELETE https://sms.messagewhiz.com/api/3/campaign/{id}
Templates
You can write the text of your message immediately before sending it, or use a predefined template for it. A message template is a message saved on the MessageWhiz platform that can be reused for new messages with similar content.
Create a Template
Example Request
POST /api/3/template HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"FirstTemplate",
"body": "HI!"
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.014043792,
"result": {
"id": 46126,
"name": "FirstTemplate",
"body": "HI!",
"enabled": true
}
}
Create a Template from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/template
Request Body
In the request body specify details for the Template that will be created:
name(string)
- Template Spinner name,body(string)
- a text body of the message Template.
Get Templates
Request Example
GET /api/3/template? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.007669944,
"result": [
{
"enabled": true,
"id": 46126,
"user_id": 3191,
"name": "FirstTemplate",
"body": "HI!"
},
{
"enabled": true,
"id": 46125,
"user_id": 3191,
"name": "1",
"body": "Test test {shorten_url}"
}
]
}
Get Templates from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/template
Query Parameters
You can include several parameters to your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active templates |
filter |
disabled | filtering by the specific template name |
start |
0 | the number of items to skip |
Modify a Template
Request Example
PUT /api/3/template/46126 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"AnotherTemplateName"
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.019078568,
"result": {
"id": 46126,
"name": "AnotherTemplateName",
"body": "HI!",
"enabled": true
}
}
To modify a specific Template, include its ID in the query:
PUT https://sms.messagewhiz.com/api/3/template/{id}
Request Body
In the request body specify the value you want to modify, for instance:
{
"name":"AnotherTemplateName"
}
If the body
is specified in the request body for a PUT request, the previous Template text will be overwritten.
Disable a Template
Request Example
DELETE /api/3/template/46126 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.01208964,
"result": true
}
To remove a specific Template from your MessageWhiz account, include its ID in the query:
DELETE https://sms.messagewhiz.com/api/3/template/{id}
Triggers
One of the sending conditions that MessageWhiz provides is Trigger. Default triggers are used to postpone the sending of the message until a specific event occurs to trigger its transmission.
Create a Trigger
Example Request
POST /api/3/trigger HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"newTrigger"
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.116146556,
"result": {
"id": 5677,
"name": "newTrigger",
"uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
"enabled": 1,
"short_url": "https://0nz0.com/jBR4d",
"trigger_type_id": 1
}
}
Create a Trigger from your MessageWhiz account:
POST https://sms.messagewhiz.com/api/3/trigger
Request Body
In the request body specify the Trigger "name"
that will be created.
In response you will receive a short_url
. The message or broadcast will not be sent until the link is clicked on or activated.
Get a Trigger
Request Example
GET /api/3/trigger? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.007109016,
"result": [
{
"id": 5677,
"name": "newTrigger",
"uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
"enabled": 1,
"short_url": "https://0nz0.com/jBR4d",
"trigger_type_id": 1,
"details": null,
"date": null,
"flight_details.flight_number": null,
"flight_details.arrival_date": null
}
]
}
Get Trigger from your MessageWhiz account:
GET https://sms.messagewhiz.com/api/3/trigger
Query Parameters
You can include several parameters to your GET query in order to receive only the data you need.
Parameter | Default | Description |
---|---|---|
limit |
10 | the number of items to fetch |
enabled |
true | fetch only active triggers |
filter |
disabled | filtering by the specific trigger name |
start |
0 | the number of items to skip |
Modify a Trigger
Request Example
PUT /api/3/trigger/5677 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"name":"#"
}
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.011503284,
"result": {
"id": 5677,
"name": "#",
"uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
"enabled": 1,
"short_url": "https://0nz0.com/jBR4d"
}
}
To modify a specific Trigger include its ID in the query:
PUT https://sms.messagewhiz.com/api/3/trigger/{id}
Request Body
In the request body specify the new value of name, for instance:
{
"name":"#"
}
Disable a Trigger
Request Example
DELETE /api/3/trigger/5677 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Response Example (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.014187964,
"result": true
}
To remove a specific Trigger from your MessageWhiz account, include its ID in the query:
DELETE https://sms.messagewhiz.com/api/3/trigger/{id}
Delivery report
Get a delivery report
Example Request
POST /api/3/DeliveryReport HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json
{
"bid": 123123
}
Example Response (200 OK)
{
"errorCode": 0,
"errorMessage": "",
"errorType": "",
"executionTime": 0.176761073,
"result": [
{
"broadcast_id": 123123,
"sent": 0,
"delivered": 1,
"undelivered": 0,
"rejected": 0,
"expired": 0,
"failed": 0
}
]
}
To get the delivery report of a certain broadcast:
POST https://sms.messagewhiz.com/api/3/DeliveryReport
You should pass only one parameter in the body
bid (integer)
- id of the broadcast which delivery report should be fetched
In case the broadcast is a V3 smart broadcast (Manual/CTR threshold) each segment DLR will be shown in a separate object in the response.
DLR to webhook
Example Response for broadcasts
{
"dlrs" : [ { "segment_id":100001,
"_id":"611f9cdf8d0a4976d8d8462aaaac",
"broadcast_id":1100001,
"recipient":"3801100001",
"price":11.8,
"task_state":2,
"updated":1629461739834
},
{ "segment_id":100002,
"_id":"611f9cdf8d0a4976d8d8462aaaaad",
"broadcast_id":1100002,
"recipient":"3801100002",
"price":11.8,
"task_state":2,
"updated":1629461739834
},
{ "segment_id":100003,
"_id":"611f9cdf8d0a4976d8d8462aaae",
"broadcast_id":1100003,
"recipient":"3801100003",
"price":11.8,
"task_state":2,
"updated":1629461739834
}
],
"custom_parameter":"1234abcd5678efgh"
}
Example Response for tiny singles
{
"dlrs" : [
{ "segment_id":100005,
"_id":"611f9cdf8d0a4976s8d8462aaaac",
"broadcast_id":1100005,
"recipient":"3801100001",
"price":1.8,
"task_state":2,
"updated":1629461732834
}],
"pduDLR": {
"sent_count": 2,
"delivered_count": 1
}
}
API users can receive DLR reports to a defined URL with 2 timeout parameters: T1 and T2. Currently this feature is enabled only after configurations by the technical team. Each client should provide Webhook URL and a T1 parameter (parameter T2 is optional). Minimum value for parameters T1 and T2 is 3 minutes.
Configuration Parameters
Required parameters
Webhook URL
- the URL to which DLR statuses will be sent.T1
- timeout parameter in minutes, amount of time after which the DLR statuses will be sent to webhook URL (minimum value 5 minutes)
Optional parameters
T2
- timeout parameter in minutes, amount of time after which the DLR statuses will be sent to webhook URL the second time (minimum value 5 minutes)
Response parameters
segment_id
- the ID of a broadcast segmentbroadcast_id
- the unique identifier of (ID) of the broadcast_id
- the internal DLR status IDprice
- the cost per each messageupdated
- internal timestamp of the last DLR status updatetask_state
- the internal ID of DLR status
task_state
to DLR status correlation:
0
- Sent
2
- Delivered
9
- Failed
8
- Rejected
5
- Undelivered
3
- Expired
custom_parameter
- custom parameter up to 40 characters, that was specified in request for Broadcast or Single creationpduDLR
- the delivery statuses each message PDU (available only for singles and tiny singles) in format amount of PDU in each DLR status. In case there are no PDUs in some DLR status - it will not be sent in object.
Example:
"pduDLR": {
"sent_count": 1,
"delivered_count": 2,
"undelivered_count": 0, //will not be present in response
"rejected_count": 0, //will not be present in response
"expired_count": 0 //will not be present in response
}
Response Error Messages
You may receive the following error codes from MessageWhiz API in response to your request:
Error Code | Meaning |
---|---|
400 | Bad Request -- Invalid parameters specified |
401 | Unauthorized -- API key is missing or invalid |
403 | Forbidden -- User/company is either disabled or doesn't have enough permissions |
404 | Not found -- An entity is not found |
409 | Duplicate entry |