Download OpenAPI specification:Download
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.
You must replace apikey
with your personal API key.
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:
<apikey>
Personal API key
<url>
URL from which API is accessed - https://sms.messagewhiz.com/
To send a single message from your MessageWhiz account
api_key required | string An API key of your account |
from required | string Provide here the Sender name |
text required | string Text of the message that the recipient will see; can contain text and links |
to required | string Phone number of the recipient |
callback | string The URL of callback to which DLR statuses per single message will be sent |
client_ref | string Custom parameter up to 160 characters, will be present in response for Single creation |
{- "api_key": "<apikey>",
- "to": "2605876689",
- "from": "sender",
- "text": "sample message"
}
{- "message_id": "rbzAV2NXxJ_u5bDL35Hop"
}
{ }
OTP (One-Time Password) feature provides a robust and flexible authentication solution for enhancing the security of user transactions and access control. This feature allows organizations to either generate an OTP using our secure API or use their own OTP code. To send a message with a verification code, the organization should specify the messaging channel and add any additional details relevant to the message.
We have two options:
NOTE:
All requests submitted for the OTP API:
Send OTP https://sms.mmdsmart.com/otp
api_key required | string The API key for the MMDSmart OTP API |
to required | string The end user's phone number you want to send a message to, as a string of digits without spaces or special characters, beginning with the country dialing code. |
from required | string This parameter allows you to set a specific Sender name to be used on an OTP message sent to the end user. |
verify_code required | number [ 1 .. 999999999 ] The verification code from the client’s side used for the code challenge. |
channel required | string Default: "sms" Value: "sms" Channel that is set for sending OTP |
use_case | string Value: "AUTH" Need to set “AUTH”. Otherwise the OTP can’t be sent |
language | string Default: "en" Language of the template |
client_ref | string Optional context value that will be send back with any response / update related to this request. |
callback | string Optional callback URL that will be called once the status of the OTP delivery changes |
{- "api_key": "<apikey>",
- "to": "1234567890",
- "from": "Sender Name",
- "verify_code": 1234,
- "channel": "sms"
}
{- "message_id": "123-abc-456-def-789"
}
{- "message_id": "1234567890",
- "sender": "MMDSmart",
- "recipient": "1234567890",
- "content": "lang: en , use_case: AUTH, code [generated]",
- "client_ref": "1234567890",
- "state": 1,
- "status": "ENROUTE",
- "timestamp": "2022-01-01T00:00:00Z",
- "otp_vendor": "sms"
}
id required | string The message id |
apikey required | string The api key |
GET /otp/status/rbzAV2NXxJ_u5bDL35Hop?apikey=YOUR_API_KEY HTTP/1.1 Host: sms.messagewhiz.com
{- "message_id": "1234567890",
- "from": "MMDSmart",
- "to": "1234567890",
- "client_ref": "1234567890",
- "state": 1,
- "status": "ENROUTE",
- "timestamp": "2022-01-01T00:00:00Z",
- "channel": "sms"
}
apikey required | string The api key |
OTP verification parameters
message_id required | string The message ID where the OTP code was sent |
verify_code required | string The OTP code that was entered by the user |
{- "message_id": "string",
- "verify_code": "string"
}
{- "client_ref": "client:1234567890|id:0978,ref:123",
- "message_id": "string",
- "verified": true
}
To Send a broadcast via API
broadcast_type required | integer Value: 11 Broadcast type for Base |
campaign_id required | integer An ID of a previously created active Campaign |
message_body required | string [ 1 .. 100000 ] characters Text of the message that the recipient will see; can contain text, links, and tokens |
name required | string [ 1 .. 64 ] characters Broadcast name |
recipient_list_ids required | string [ 0 .. 1000 ] characters IDs of previously created Recipient Lists |
sender_ids required | string [ 0 .. 1000 ] characters ^[0-9]+(,[0-9]+)*$ IDs of previously created Senders |
delay | integer >= 0 The broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes |
send_date | string <date-time> Specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z") |
sender_list_ids | string [ 0 .. 1000 ] characters ^[0-9]+(,[0-9]+)*$ IDs of previously created Sedners Lists |
template_id | integer Id of the message template, if you want to use a specific template for message body |
trigger_id | integer Id of the trigger that will be used to send the broadcast (may be used instead of |
unsubscriber_list_ids | string [ 0 .. 1000 ] characters IDs of previously created Unsubscribe Lists |
utc_offset | integer [ -720 .. 720 ] Specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0) |
{- "name": "broadcast",
- "campaign_id": 1,
- "broadcast_type": 11,
- "unsubscriber_list_ids": "",
- "sender_ids": "23",
- "recipient_list_ids": "12",
- "message_body": "broadcast message"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.160202353,
- "result": {
- "broadcastID": 331,
- "segmentID": 493,
- "custom_parameter": "1234abcd5678efgh"
}
}
To Estimate a broadcast via API
broadcast_type required | integer Value: 11 Broadcast type for Base |
message_body required | string [ 1 .. 100000 ] characters Text of the message that the recipient will see; can contain text, links, and tokens |
recipient_list_ids required | string [ 0 .. 1000 ] characters IDs of previously created Recipient Lists |
template_id | integer Id of the message template, if you want to use a specific template for message body |
unsubscriber_list_ids | string [ 0 .. 1000 ] characters IDs of previously created Unsubscribe Lists |
{- "broadcast_type": 11,
- "recipient_list_ids": "288696",
- "unsubscriber_list_ids": "",
- "message_body": "sample"
}
{- "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",
- "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
}
}
}
Get Broadcasts from your MessageWhiz account
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
filter | string [ 1 .. 255 ] characters Default: "disabled" filtering by the specific broadcast field. Filter has a specific format:
Available parameters are: name - pattern for the broadcast name (the actual name will contain the given string) type - type of the broadcast
parent_id - parent_id of the broadcast (type is automatically set to 3) start_date - start of the date range by which to filter end_date - end of the date range by which to filter filterBy - determines by which date broadcasts will be filtered (create date or send date) create_date - filters by the date of broadcast creation send_date - filters by the broadcasts send date For example filter with such format:
Will find all the smart broadcasts (both approaches) that was created later than 06/01/2021 12:00 AM which name contains sample substring |
orderby | string <= 50 characters Default: "create_date DESC" Criteria and order by which the list will be sorted |
GET /api/3/Broadcast/List HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "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.5,
- "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
}
}
]
}
An endpoint on Segment Based architecture which enables creating a Base Broadcast and sending it to a new Recipient list withone request
message_body required | string [ 1 .. 100000 ] characters Text of the message that the recipient will see; can contain text, links, and tokens |
sender required | string Name of the Sender |
recipients required | Array of objects [ 1 .. 100000 ] characters Json file with all needed data (phone number, first name, last name, URL ect. per each recipient) |
name | string [ 1 .. 64 ] characters 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 name |
send_date | string <date-time> Specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z") |
sender_id | integer ID of previously created sender |
utc_offset | integer [ -720 .. 720 ] Specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0) |
{- "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",
},
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.351626371,
- "result": [
- {
- "broadcastID": 333,
- "segmentID": 495
}
]
}
broadcast_id required | integer Id of the broadcast to be continued |
sender_ids required | boolean Specifies if the segment should be sent as soon as possible |
segment_size required | integer >= 1 Ount of the recipients whose messages will be sent within the segment |
message_body required | string [ 1 .. 100000 ] characters Message for the segment |
next_segment_size | integer >= 1 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) |
recipient_cap | integer or string >= 1 no_limit Default: "no_limit" 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) |
send_date | string Date when the segment will be send (may be used instead of send_now) |
sender_list_ids | string [ 0 .. 1000 ] characters ^[0-9]+(,[0-9]+)*$ Ids of the sender lists which will be used for the created segment (may be used instead of |
first_segment_size | integer >= 1 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) |
template_ids | string Ids of the templates that will be used for the created segment (may be used instead of message_body) |
utc_offset | integer [ -720 .. 720 ] Specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0) |
{- "broadcast_id": 111,
- "message_body": "sample",
- "segment_size": 1,
- "send_now": true,
- "sender_ids": "1",
- "utc_offset": 180
}
{- "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
}
}
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 from your MessageWhiz account
In the request body specify details for the Campaign that will be created. Date and time are expressed according to ISO 8601.
Note , the Campaign end_date
cannot be earlier than start_date
.
name required | string [ 1 .. 50 ] characters ^[^\s']+(\s+[^\s]+)*$ Campaign name |
end_date | string <date-time> Campaign end date |
start_date | string <date-time> Campaign start date |
{- "name": "CampaignName",
- "start_date": "2020-07-22T21:00:00.000Z",
- "end_date": "2020-09-25T21:00:00.000Z"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.044941952,
- "result": {
- "id": 46279,
- "is_default": 0,
- "name": "MyCampaign",
- "start_date": "2020-07-22T21:00:00.000Z",
- "end_date": "2020-09-25T21:00:00.000Z",
- "enabled": true
}
}
Get Campaigns from your MessageWhiz account
You can include several parameters in your GET query in order to receive only the data you need. 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
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
start | integer >= 0 Default: 0 The number of items to skip |
filter | string [ 1 .. 100 ] characters Filtering by the specific campaign name |
enabled | string Default: "true" Enum: "true" "false" "all" Fetch only active campaigns |
GET /api/3/Campaign/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "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 Campaign detailes from your MessageWhiz account
id required | string Campaign ID |
GET /api/3/Campaign/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.044941952,
- "result": {
- "id": 2134,
- "is_default": 0,
- "name": "CampaignName",
- "start_date": "2020-07-22T21:00:00.000Z",
- "end_date": "2020-09-25T21:00:00.000Z",
- "enabled": true
}
}
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.
id required | string Campaign ID |
name | string [ 1 .. 50 ] characters ^[^\s']+(\s+[^\s]+)*$ Campaign name |
start_date | string <date-time> Campaign start date |
end_date | string <date-time> Campaign end date |
{- "end_date": "2021-03-25T21:00:00.000Z"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.026245764,
- "result": {
- "id": 2134,
- "is_default": 0,
- "name": "CampaignName",
- "start_date": "2020-07-22T21:00:00.000Z",
- "end_date": "2021-03-25T21:00:00.000Z",
- "enabled": true
}
}
To modify a specific Campaign from your MessageWhiz account, include its ID in the query
id required | string Campaign ID |
name | string [ 1 .. 50 ] characters ^[^\s']+(\s+[^\s]+)*$ Campaign name |
start_date | string <date-time> Campaign start date |
end_date | string <date-time> Campaign end date |
{- "enabled": "1"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.026245764,
- "result": {
- "id": 2134,
- "is_default": 0,
- "name": "CampaignName",
- "start_date": "2020-07-22T21:00:00.000Z",
- "end_date": "2021-03-25T21:00:00.000Z",
- "enabled": true
}
}
To remove a specific Campaign from your MessageWhiz account, add its ID as parameter to the query
id required | string Campaign ID |
DELETE /api/3/Campaign/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
To get the delivery report of a certain broadcast:
POST https://sms.messagewhiz.com/api/3/DeliveryReport
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.
bid required | string id of the broadcast which delivery report should be fetched |
{- "bid": "225544"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.044941952,
- "result": {
- "broadcast_id": 123123,
- "sent": 0,
- "delivered": 1,
- "undelivered": 0,
- "rejected": 0,
- "expired": 0,
- "failed": 0
}
}
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 from your MessageWhiz account
name required | string Link name |
url required | string Link url itself, in the URI format |
object Links based on detected user platform |
{- "name": "Link1",
- "platform_based_links": {
}
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.01954006,
- "result": {
- "id": 165655,
- "name": "Link1",
- "enabled": true,
- "type": 0,
- "platform_based_links": {
}
}
}
Get Links from your MessageWhiz account
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
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
enabled | boolean Fetch only active items |
filter | string [ 1 .. 255 ] characters Default: "disabled" Filtering by the specific link name/url |
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
GET /api/3/Link/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.006230324,
- "result": [
- {
- "enabled": true,
- "id": 146746,
- "name": "test",
}
]
}
To modify a specific Link, you should specify its ID in the query
id required | integer Item ID |
name required | string Link name |
url required | string Link url itself, in the URI format |
{- "name": "FirstLink",
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.011805652,
}
To remove a specific Link, you should include its ID in the query
id required | integer Item ID |
DELETE /api/3/Link/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
To receive conversion data from a certain link
url required | string The link to monitor conversion |
{- "url": "messagewhiz.com"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.12326038,
- "result": {
- "conversion": 100,
- "totalRecipients": 1,
- "clicks": 1
}
}
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 an empty Link List from your MessageWhiz account
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
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
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)
multipart/formdata
requestname required | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Link List name |
linkIds | Array of integers Array of link lists ids |
Array of objects An array of link objects | |
object The markers to specify the type of stored data in the columns. The mapping structure should correspond to the structure presented in the uploaded file/array |
{- "name": "FirstLinkList",
- "linkIds": [
- "311"
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.017949384,
- "result": {
- "id": 6940,
- "name": "FirstLinkList",
- "enabled": true,
- "linkListLength": 1,
- "warning": ""
}
}
Get Link Lists from your MessageWhiz account
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
enabled | boolean Fetch only active items |
filter | string [ 1 .. 255 ] characters Default: "disabled" Filtering by the specific link list name |
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
GET /api/3/LinkList/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.056359856,
- "result": [
- {
- "id": 6943,
- "name": "LinksList",
- "enabled": 1,
- "conversionCount": 0
}
]
}
If you want to partially update the resource, you can use PATCH
id required | integer Item ID |
required | object The markers to specify the type of stored data in the columns. The mapping structure should correspond to the structure presented in the uploaded file/array |
name required | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Link List name |
doc required | file An absolute path to the file on your device |
--form 'doc=@/home/user/Downloads/SecondLinkList.csv' \ --form 'mapping={"0":"name", "1":"url"}' \ --form 'name=NewList'
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.009358444,
- "result": {
- "id": 2134,
- "enabled": 1
}
}
id required | integer Item ID |
enabled required | integer Enum: 1 0 |
{- "enabled": 1
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.009358444,
- "result": {
- "id": 2134,
- "enabled": 1
}
}
Remove a specific Link List from your MessageWhiz account by ID
id required | integer Item ID |
DELETE /api/3/LinkList/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
Get an array of Links from a specific Link List by ID
id required | integer Item ID |
GET /api/3/LinkList/{id}/links HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.010940972,
- "result": [
- {
- "id": 2134,
- "links": [
]
}
]
}
To remove a Link from the Link List, include Link List ID in the query and specify Link ID as required parameter
listID required | integer Link List Id |
linkID required | integer Link Id |
DELETE /api/3/LinkList/{listID}/links?id={linkID} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
To add multiple new Links to the Link List, you should include Link List ID in the query
id required | integer Item ID |
Array of objects An array of link objects |
{- "links": [
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.064860264,
- "result": {
- "enabled": true,
- "id": 2134,
- "name": "FirstLinkList",
- "user_id": 3191,
- "company_id": 3182
}
}
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:
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 by importing file of contacts
NOTE Please note that up to 100,000 recipients can be designated in a single broadcast.
To check if your file fits, you can preview(/Recipient List/preview) it
truncate required | boolean Default: false Automatically truncates fields in the list if they are longer than allowed. if truncate===false and there are fields in the list that exceed the limits, an error while loading occurs. |
required | Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) (Array of numbers to create a recipient list.) The markers to specify the type of stored data in the columns. Possible markers:
(e.g The mapping structure should correspond to the structure presented in the uploaded file. first_name, last_name - max length is 50 symbols, email, url - 255, other - 5000. The metadata stored in these marked columns might be used as tokens to send personalized messages. |
name required | string [ 1 .. 50 ] characters Name of the created recipient list |
doc | file An absolute path to the file on your device |
--form 'doc=@/home/user/Downloads/numbers_9.csv' \ --form 'mapping={"0":"phone_number", "1":"first_name"}'\ --form 'name=FirstRecipientList'
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012664016,
- "result": {
- "inserted": 2,
- "total": 2,
- "wrong": 0,
- "duplicate": 0,
- "recipient_list_id": 267628
}
}
Create a Recipient List by adding the phone numbers manually
name required | string [ 1 .. 50 ] characters Name of the created recipient list |
numbers required | Array of strings |
{- "name": "MyRecipientsList",
- "numbers": [
- "380503327227",
- "380848122639"
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012664016,
- "result": {
- "inserted": 2,
- "total": 2,
- "wrong": 0,
- "duplicate": 0,
- "recipient_list_id": 267628
}
}
Get Recipient Lists from your MessageWhiz account:
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
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
enabled | string Default: "true" Enum: "true" "false" "all" Fetch only active lists |
filter | string [ 1 .. 100 ] characters Filtering by the specific list name |
start | integer >= 0 Default: 0 The number of items to skip |
GET /api/3/RecipientList/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "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 recipients from the specific Recipient List using its ID
id required | integer Recipient List ID |
GET /api/3/RecipientList/{id}/recipients HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012814664,
- "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 an array of phone numbers from the specific Recipient List using its ID
id required | integer Recipient List ID |
GET /api/3/RecipientList/{id}/listNumbers HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012814664,
- "result": [
- "6593333311",
- "6593333322",
- "6593333333",
- "6593333344"
]
}
MessageWhiz API provides you with the possibility to preview your file of contacts before importing it and creating the Recipient List
doc | file An absolute path to the file on your device |
--form 'doc=@/home/user/Downloads/numbers_9.csv'
{- "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
]
}
Download specific Recipient List using its ID and save the response
id required | Array of integers Sender List ID |
GET /api/3/RecipientList/{id}/download HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
"phone_number";"first_name" "6593333311";"Anthony" "6593333322";"Bob" "6593333333";"Jonathan" "6593333344";"Alex"
To modify a specific Recipient List by adding new numbers manually or changing the list name, add its ID to the query
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:
id required | integer Recipient List ID |
name required | string [ 1 .. 50 ] characters Name of the created recipient list |
numbers required | Array of strings |
{- "name": "MyRecipientsList",
- "numbers": [
- "380503327227",
- "380848122639"
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.019542036,
- "result": {
- "inserted": 2,
- "wrong": 0,
- "duplicate": 0,
- "total": 2,
- "recipient_list_id": 267891,
- "count": 5
}
}
id required | integer Recipient List ID |
name | string [ 1 .. 50 ] characters Name of the created recipient list |
numbers | Array of strings |
{- "name": "MyRecipientsList",
- "numbers": [
- "380503327227",
- "380848122639"
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.019542036,
- "result": {
- "inserted": 2,
- "wrong": 0,
- "duplicate": 0,
- "total": 2,
- "recipient_list_id": 267891,
- "count": 5
}
}
Replace the entire existing Recipient List with the new imported one
id required | integer Recipient List ID |
required | Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) or Array of numbers to create a recipient list. (object) (Array of numbers to create a recipient list.) The markers to specify the type of stored data in the columns. Possible markers:
(e.g The mapping structure should correspond to the structure presented in the uploaded file. first_name, last_name - max length is 50 symbols, email, url - 255, other - 5000. The metadata stored in these marked columns might be used as tokens to send personalized messages. |
name required | string [ 1 .. 50 ] characters Name of the created recipient list |
doc | file An absolute path to the file on your device The mapping structure should correspond to the structure presented in the new uploaded file. |
--form 'doc=@/home/user/Downloads/RecipientList.csv' \ --form 'mapping={"0":"phone_number", "1":"first_name"}'\ --form 'name=FirstRecipientList'
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012664016,
- "result": {
- "inserted": 2,
- "total": 2,
- "wrong": 0,
- "duplicate": 0,
- "recipient_list_id": 267628
}
}
To remove a specific Recipient List from your MessageWhiz account, you should include its ID the query
id required | integer Recipient List ID |
DELETE /api/3/RecipientList/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
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 from your MessageWhiz account
name required | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Sender name |
{- "name": "FirstSender"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.044570548,
- "result": {
- "id": 28938892,
- "name": "FirstSender",
- "enabled": true
}
}
Get Senders from your MessageWhiz account
You can include several parameters in your GET query in order to receive only the data you need.
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
enabled | string Default: "true" Enum: "true" "false" "all" Fetch only active lists |
filter | string [ 1 .. 100 ] characters Filtering by the specific sender name |
start | integer >= 0 Default: 0 The number of items to skip |
GET /api/3/Sender/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.013848856,
- "result": [
- {
- "enabled": true,
- "id": 28938892,
- "name": "FirstSender"
}, - {
- "enabled": true,
- "id": 28905672,
- "name": "test"
}
]
}
To modify a specific Sender from your MessageWhiz account, include its ID in the query
In the request body specify the new sender name and status for the selected Sender entity, for instance:
{ "name": "FirstSender", "enabled": 0 }
id required | integer Example: 2134 Sender ID |
name required | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Sender name |
enabled required | boolean Make the item active |
{- "name": "FirstSender",
- "enabled": true
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.021960496,
- "result": {
- "id": 2134,
- "name": "FirstSender",
- "enabled": true
}
}
If you want to partially update the resource, you can use PATCH
id required | integer Sender ID |
name | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Sender name |
enabled | boolean Make the item active |
{- "name": "FirstSender"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.021960496,
- "result": {
- "id": 2134,
- "name": "FirstSender",
- "enabled": true
}
}
To remove a specific Sender from your MessageWhiz account, you should include its ID to the query
id required | integer Sender ID |
DELETE /api/3/Sender/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
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 from your MessageWhiz account
In case of all invalid senderIds, Senders will not be added to the list, and the list will be created empty.
name required | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Sender List name |
senderIds required | Array of numbers An array of IDs of the Senders that the list will consist of |
{- "name": "FirstSenderList",
- "senderIds": [
- 32154,
- 65412
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012814664,
- "result": {
- "id": 5456,
- "name": "FirstSenderList",
- "enabled": true,
- "count": 2
}
}
Get Sender Lists from your MessageWhiz account
enabled | boolean Fetch only active items |
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
filter | string [ 1 .. 100 ] characters Filtering by the specific sender list name |
GET /api/3/SenderList/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.00982226,
- "result": [
- {
- "enabled": true,
- "id": 5456,
- "name": "FirstSenderList",
- "count": 2
}, - {
- "enabled": true,
- "id": 5455,
- "name": "SenderList",
- "count": 1
}
]
}
To modify a specific Sender List by adding new Senders and changing the list name, add its ID to the query
id required | integer Item ID |
name required | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Sender List name |
senderIds required | Array of integers non-empty unique [ items [ 1 .. 4294967295 ] ] Senders ids list |
enabled required | boolean
|
{- "name": "FirstSenderList",
- "senderIds": [
- 4324,
- 4321
], - "enabled": true
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.040806108,
- "result": {
- "id": 2134,
- "name": "FirstSenderList",
- "enabled": true,
- "count": 2
}
}
To modify a specific Sender List by adding new Senders and changing the list name, add its ID to the query
id required | integer Senders List ID |
name | string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$ Sender List name |
senderIds | Array of integers non-empty unique [ items [ 1 .. 4294967295 ] ] Senders ids list |
enabled | boolean
|
{- "enabled": true
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.009910892,
- "result": {
- "id": 2134,
- "enabled": 1
}
}
To remove a specific Sender List from your MessageWhiz account, you should include its ID the query
id required | integer Item ID |
DELETE /api/3/SenderList/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
To add Senders to a Sender List from your MessageWhiz account, specify Sender List ID
listID required | integer Senders ids |
ids | Array of integers An array of Sender Ids |
{- "ids": [
- 28899614,
- 28899615
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.032248508,
- "result": [
- 28899614,
- 28899615
]
}
Get an array of Sender objects from a specific Sender List
listID required | integer Senders ids |
GET /api/3/SenderList/{listID}/senders HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.008722612,
- "result": {
- "id": 2134,
- "senders": [
- {
- "senderId": 28905674,
- "name": "test2"
}, - {
- "senderId": 28938892,
- "name": "FirstSender"
}
]
}
}
To remove a Sender from the Sender List, you should include Sender List ID in the query and specify Sender ID as required parameter
/api/3/senderList/{id}/senders?id={senderID}
listID required | integer Senders ids |
DELETE /api/3/SenderList/{listID}/senders HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
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 from your MessageWhiz account
body required | string A text body of the message Template |
name required | string Template name |
{- "name": "FirstTemplate",
- "body": "HI!"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.014043792,
- "result": {
- "id": 46126,
- "name": "FirstTemplate",
- "body": "HI!",
- "enabled": true
}
}
Get Templates from your MessageWhiz account
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
filter | string [ 1 .. 255 ] characters Default: "disabled" filtering by the specific item field. Filter has a specific format:
|
enabled | boolean Fetch only active items |
GET /api/3/Template/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "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}"
}
]
}
To modify a specific Template, include its ID in the query
If the body is specified in the request body for a PUT request, the previous Template text will be overwritten.
id required | integer Item ID |
body | string A text body of the message Template |
name | string Template name |
{- "name": "AnotherTemplateName",
- "body": "HI!"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.019078568,
- "result": {
- "id": 2134,
- "name": "AnotherTemplateName",
- "body": "HI!",
- "enabled": true
}
}
To remove a specific Template from your MessageWhiz account, include its ID in the query
id required | integer Item ID |
DELETE /api/3/Template/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
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 from your MessageWhiz account:
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.
name required | string Trigger name |
{- "name": "newTrigger"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.116146556,
- "result": {
- "id": 5677,
- "name": "newTrigger",
- "uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
- "enabled": 1,
- "trigger_type_id": 1
}
}
Get Trigger from your MessageWhiz account
You can include several parameters to your GET query in order to receive only the data you need
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
filter | string [ 1 .. 255 ] characters Default: "disabled" filtering by the specific trigger name |
enabled | boolean Fetch only active items |
GET /api/3/Trigger/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.007109016,
- "result": [
- {
- "id": 5677,
- "name": "newTrigger",
- "uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
- "enabled": 1,
- "trigger_type_id": 1,
- "details": null,
- "date": null,
- "flight_details.flight_number": null,
- "flight_details.arrival_date": null
}
]
}
To modify a specific Trigger, include its ID in the query
id required | integer Item ID |
In the request body specify the new value of name, for instance:
{ "name":"#" }
name required | string Trigger name |
{- "name": "#"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.019078568,
- "result": {
- "id": 2134,
- "name": "#",
- "uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
- "enabled": 1,
}
}
To remove a specific Template from your MessageWhiz account, include its ID in the query
id required | integer Item ID |
DELETE /api/3/Trigger/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
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 from your MessageWhiz account
name required | string Word Spinner name |
words required | Array of strings An array of word synonyms |
{- "name": "Fit32",
- "words": [
- "wo",
- "three",
- "spinner",
- "greeetinnngsss",
- "four",
- "test",
- "one",
- "five"
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.041090464,
- "result": {
- "name": "Fit32",
- "words": [
- "wo",
- "three",
- "spinner",
- "greeetinnngsss",
- "four",
- "test",
- "one",
- "five"
], - "enabled": true,
- "id": 10520
}
}
Get Word Spinners from your MessageWhiz account
You can include several parameters to your GET query in order to receive only the data you need
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
filter | string [ 1 .. 255 ] characters Default: "disabled" filtering by the specific item field. Filter has a specific format:
|
enabled | boolean Fetch only active items |
GET /api/3/Spinner/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.008722612,
- "result": [
- {
- "words": [
- "wo",
- "three",
- "spinner",
- "greeetinnngsss",
- "four",
- "test",
- "one",
- "five"
], - "enabled": true,
- "id": 10520,
- "name": "Fit32"
}
]
}
To modify a specific Word Spinner, include its ID in the query
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.
id required | integer Item ID |
name required | string Word Spinner name |
words required | Array of strings An array of word synonyms |
{- "name": "Fit32",
- "words": [
- "wo",
- "three",
- "spinner",
- "greeetinnngsss",
- "four",
- "test",
- "one",
- "five"
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.014242532,
- "result": {
- "name": "FirstSpinner",
- "words": [
- "wo",
- "three",
- "spinner",
- "greeetinnngsss",
- "four",
- "test",
- "one",
- "five"
], - "enabled": true,
- "id": 2134
}
}
To modify a specific Word Spinner, include its ID in the query
The Word Spinner might be disabled, by specifying it in the request body for a PATCH request:
{ "enabled": "0" }
id required | integer Item ID |
name | string Word Spinner name |
words | Array of strings An array of word synonyms |
enabled | boolean Set sinner active |
{- "enabled": "0"
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.0242746,
- "result": {
- "enabled": 0
}
}
To remove a specific Word Spinner from your MessageWhiz account, include its ID in the query
id required | integer Item ID |
DELETE /api/3/Spinner/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
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.
NOTE: To enable recipients to opt out of your broadcasts, you should include
{{unsubscription_link:ID}}
token that generates a link to your message body.
The recipient clicks on the unsubscribe link and confirms unsubscription, the user’s data will be added to the
unsubscribe list associated with this token.
Create an Unsubscribe List by importing file of contacts
name required | string [ 1 .. 50 ] characters The name of the Unsubscribe List |
required | object or object or object or object or object or object or object or object or object or object The markers to specify the type of stored data in the columns. Possible markers:
(e.g 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 required | file An absolute path to the file on your device |
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \ --form 'mapping={"0":"phone_number", "1":"first_name"}' \ --form 'name=FirstRecipientList'
{- "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
name required | string [ 1 .. 50 ] characters The name of the Unsubscribe List |
numbers required | Array of integers unique Default: [] Array of phone numbers that the Unsubscribe List consists of |
{- "name": "FirstUnsubscribeList",
- "numbers": [
- 380502222233
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.025868544,
- "result": {
- "enabled": true,
- "id": 21534,
- "name": "FirstUnsubscribeList",
- "company_id": 3182,
- "unsubscribers_amount": 1,
- "user_id": 3191
}
}
Get Unsubscribe Lists from your MessageWhiz account
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/UnsubscribeList?filter=name=FirstUnsubscribeList
limit | integer [ 1 .. 100 ] Default: 10 The number of items to fetch |
enabled | boolean Fetch only active items |
filter | string [ 1 .. 255 ] characters Default: "disabled" filtering by the specific item field. Filter has a specific format:
|
start | integer >= 0 Default: 0 Example: start=0 The number of items to skip |
GET /api/3/UnsubscribeList/ HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.028108664,
- "result": [
- {
- "id": 21534,
- "name": "FirstUnsubscribeList",
- "enabled": 1,
- "unsubscribers_amount": 3
}
]
}
Replace the entire existing Unsubscribe List with the new imported one
id required | integer Item ID |
In the request body specify the new values for this list.
If you want to partially update the resource, you can use:
PATCH https://sms.messagewhiz.com/api/3/UnsubscribeList/{id}
doc required | file An absolute path to the file on your device |
required | object or object or object or object or object or object or object or object or object or object The markers to specify the type of stored data in the columns. Possible markers:
(e.g 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. |
--form 'mapping={"0":"phone_number"}' \ --form 'doc=@/home/user/Downloads/UnsubscribeList.csv'
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.040112328,
- "result": {
- "enabled": true,
- "id": 2134,
- "name": "FirstUnsubscribeList",
- "company_id": 3182,
- "unsubscribers_amount": 4,
- "user_id": 3191
}
}
Replace the entire existing Unsubscribe List with the new imported one
id required | integer Item ID |
You can disable an unsubscribe list by entering "enabled": false
in the request body.
enabled required | any
|
{- "enabled": false
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.022112432,
- "result": {
- "id": 2134,
- "enabled": false
}
}
To remove a specific Sender List from your MessageWhiz account, you should include its ID in the path
id required | integer Item ID |
DELETE /api/3/UnsubscribeList/{id} HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.012125844,
- "result": true
}
MessageWhiz API provides you with the possibility to preview your file of contacts before actually importing it and to create the Unsubscribe List
doc required | file An absolute path to the file on your device |
--form 'doc=@/home/user/Downloads/numbers_9.csv'
{- "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
]
}
}
Download a specific Unsubscribe List using its ID and then save the response
id required | integer Item ID |
GET /api/3/UnsubscribeList/{id}/download HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
"phone_number" "380502327265" "380502222233" "380643333322"
Add phone numbers to the existing Unsubscribe List (include its ID in the query)
id required | integer Item ID |
numbers required | Array of integers unique Default: [] Array of phone numbers that the Unsubscribe List consists of |
{- "numbers": [
- "380502222233",
- "380643333322"
]
}
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.031270908,
- "result": {
- "inserted": 2,
- "alreadyExists": 0,
- "notValid": 0
}
}
Get phone numbers from the specific Unsubscribe List using its ID
id required | integer Item ID |
GET /api/3/UnsubscribeList/{id}/members HTTP/1.1 Host: sms.messagewhiz.com apikey: YOUR_COMPANY_API_KEY
{- "errorCode": 0,
- "errorMessage": "",
- "errorType": "",
- "executionTime": 0.018904092,
- "result": [
- {
- "phone_number": "380643333322"
}, - {
- "phone_number": "380502327265"
}, - {
- "phone_number": "380502222233"
}
]
}
Send a Message
Send a Message.
client_ref | string Client reference of up to 100 characters. The reference will be present in every message status. |
webhook_url | string The URL of callback to which DLR statuses per single message will be sent |
message_type required | string Value: "text" The type of message to send. You must provide |
text required | string Text size limit: 599 characters for Latin characters and digits, and 299 characters for other characters like Cyrillic, Arabic, and Chinese. |
to required | string [ 7 .. 15 ] characters The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000. |
from required | string <uuid> Agent ID |
channel required | string Value: "sms" The channel to send to. You must provide |
{- "message_type": "text",
- "text": "Hey! this is my awesome message!",
- "to": "447700900000",
- "from": "b38c2869-af85-4a00-8552-51b53667fa11",
- "channel": "sms"
}
{- "message_uuid": "b38c2869-af85-4a00-8552-51b53667fa11"
}
{- "message_uuid": "b38c2869-af85-4a00-8552-51b53667fa11",
- "to": "447700900000",
- "from": "b38c2869-af85-4a00-8552-51b53667fa11",
- "status": "delivered",
- "timestamp": "2020-01-01T14:00:00.000Z",
- "error": {
- "type": 1000,
- "title": 1000,
- "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
- "instance": "mmd-12345-76543"
}, - "client_ref": "string",
- "channel": "sms"
}
Webhook for an inbound message from a customer to you.
inboundMessageUrl required | string Webhook url. |
agentID required | string The Agent ID used as the sender's phone number |
{- "agentID": "d2130c95-f8b9-4ab0-8719-36d74af30185"
}
{- "status": 200,
- "message": "Request is successful"
}
Create customer. If the customer create is successful, you will receive a response status of 200.
phone required | string [ 3 .. 15 ] characters ^[0-9]+$ The phone number of the customer |
name | string <= 32 characters The name of the customer |
{- "phone": "145044111206"
}
{- "id": "76fdcf10-2352-4da1-ab84-4b1f7ddf8cbd",
- "chatbot_enabled": {
- "03dbaafc-a2fe-4aca-9658-dc23dffbfc18": "ENABLED_AUTO"
}, - "phone": "145044111206",
- "name": "John Smith",
- "country": "US",
- "subscriptions": { },
- "created": "2024-04-16T10:51:28.924Z",
- "modified": "2024-04-26T13:33:44.677Z",
- "chatbot_notification_received": { }
}
Get a list of customers with customers data.
offset | number Sets the first position to return from the results of the request. Default - 0 |
limit | number The number of entities to return in result. Default - 50 |
sort | string The field by which entities in result are sorted. Default - created |
order | string Enum: "ascending" "descending" Direction of entities sorting - ascending or descending. Default - descending |
search | string The field by which entities in result are searched |
name | string Could be used to filter customers by name field |
phone | string Could be used to filter customers by phone field |
[- {
- "id": "76fdcf10-2352-4da1-ab84-4b1f7ddf8cbd",
- "chatbot_enabled": {
- "03dbaafc-a2fe-4aca-9658-dc23dffbfc18": "ENABLED_AUTO"
}, - "phone": "145044111206",
- "name": "John Smith",
- "country": "US",
- "subscriptions": {
- "56a342e6-fa7b-4959-be4c-d78cecfcd885": "ACTIVE"
}, - "created": "2024-04-16T10:51:28.924Z",
- "modified": "2024-04-26T13:33:44.677Z",
- "last_message_time": "2024-04-27T13:33:44.677Z",
- "telegram_chat_id": "364870593",
- "chatbot_notification_received": { }
}
]
Retrieve customer data by providing either the customer ID or the customer phone number.
customer_id or phone required | string Customer ID or customer phone |
{- "id": "76fdcf10-2352-4da1-ab84-4b1f7ddf8cbd",
- "chatbot_enabled": {
- "03dbaafc-a2fe-4aca-9658-dc23dffbfc18": "ENABLED_AUTO"
}, - "phone": "145044111206",
- "name": "John Smith",
- "country": "US",
- "subscriptions": {
- "56a342e6-fa7b-4959-be4c-d78cecfcd885": "ACTIVE"
}, - "created": "2024-04-16T10:51:28.924Z",
- "modified": "2024-04-26T13:33:44.677Z",
- "last_message_time": "2024-04-27T13:33:44.677Z",
- "telegram_chat_id": "364870593",
- "chatbot_notification_received": { }
}
Update customer. If the customer update is successful, you will receive a response status of 204.
customer_id required | string Customer ID |
object Whether chatbot is enabled for conversations with current customer | |
name | string <= 32 characters The name of the customer |
{- "name": "CustomerName"
}
{- "title": "Bad Request",
- "detail": "invalid payload",
- "instance_id": ""
}
Delete customer. If the customer delete is successful, you will receive a response status of 204.
customer_id required | string Customer ID |
{- "title": "Bad Request",
- "detail": "invalid payload",
- "instance_id": ""
}