API docs by Redocly

MessageWhiz API (3.0.0)

Download OpenAPI specification:Download

URL: https://sms.messagewhiz.com

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/

Single

Single

To send a single message from your MessageWhiz account

Request Body schema: application/json
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

Responses

Callbacks

Request samples

Content type
application/json
{
  • "api_key": "<apikey>",
  • "to": "2605876689",
  • "from": "sender",
  • "text": "sample message"
}

Response samples

Content type
application/json
Example
{
  • "message_id": "rbzAV2NXxJ_u5bDL35Hop"
}

Callback payload samples

Callback
Content type
application/json
{ }

Send a One Time Password message

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:

  1. Client Authentication service: generated and verified code on our side is sent via SMS channel
  2. Verification code generated by the organization is sent on the MMDSmart predefined template, on a predetermined messaging channel chosen by the organization.

NOTE:

  • If verification code is not specified by the organization, it will be generated and verified by our endpoints. If the organization generates its own codes and independently validates the received codes with its own systems, the generation and validation processes are not covered by this API.
  • Please specify use case AUTH.
  • Authorization is required and must be passed by API key. API key needs to be specified in the request body.

All requests submitted for the OTP API:

Request Body schema: application/json

Send OTP https://sms.mmdsmart.com/otp

One of
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

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "api_key": "<apikey>",
  • "to": "1234567890",
  • "from": "Sender Name",
  • "verify_code": 1234,
  • "channel": "sms"
}

Response samples

Content type
application/json
{
  • "message_id": "123-abc-456-def-789"
}

Callback payload samples

Callback
POST: Response on DLR callback
Content type
application/json
{
  • "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"
}

Receive the One Time Password message status by message Id

https://sms.mmdsmart.com/otp/status/{messageid}

path Parameters
id
required
string

The message id

query Parameters
apikey
required
string

The api key

Responses

Request samples 

GET /otp/status/rbzAV2NXxJ_u5bDL35Hop?apikey=YOUR_API_KEY HTTP/1.1
Host: sms.messagewhiz.com

Response samples

Content type
application/json
{
  • "message_id": "1234567890",
  • "from": "MMDSmart",
  • "to": "1234567890",
  • "client_ref": "1234567890",
  • "state": 1,
  • "status": "ENROUTE",
  • "timestamp": "2022-01-01T00:00:00Z",
  • "channel": "sms"
}

Verify One Time Password

https://sms.mmdsmart.com/otp/verify

query Parameters
apikey
required
string

The api key

Request Body schema: application/json

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

Responses

Request samples

Content type
application/json
{
  • "message_id": "string",
  • "verify_code": "string"
}

Response samples

Content type
application/json
{
  • "client_ref": "client:1234567890|id:0978,ref:123",
  • "message_id": "string",
  • "verified": true
}

Broadcast

Send Broadcast

To Send a broadcast via API

Authorizations:
ApiKeyAuth
Request Body schema: application/json
One of
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 send_now)

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)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "broadcast",
  • "campaign_id": 1,
  • "broadcast_type": 11,
  • "unsubscriber_list_ids": "",
  • "sender_ids": "23",
  • "recipient_list_ids": "12",
  • "message_body": "broadcast message"
}

Response samples

Content type
application/json
Example
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.160202353,
  • "result": {
    }
}

Estimate Broadcast

To Estimate a broadcast via API

Authorizations:
ApiKeyAuth
Request Body schema: application/json
One of
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

Responses

Request samples

Content type
application/json
Example
{
  • "broadcast_type": 11,
  • "recipient_list_ids": "288696",
  • "unsubscriber_list_ids": "",
  • "message_body": "sample"
}

Response samples

Content type
application/json
Example
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 5.076538867,
  • "result": {
    }
}

Get Broadcasts List

Get Broadcasts from your MessageWhiz account

Authorizations:
ApiKeyAuth
query Parameters
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:

?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 broadcast

  • 10 - single broadcast

  • 11 - basic broadcast

  • 12 - smart broadcast

  • 13 - text optimisation 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:

?filter=name=sample,type=10,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

orderby
string <= 50 characters
Default: "create_date DESC"

Criteria and order by which the list will be sorted

Responses

Request samples 

GET /api/3/Broadcast/List HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.351626371,
  • "result": [
    ]
}

Single request broadcasts

An endpoint on Segment Based architecture which enables creating a Base Broadcast and sending it to a new Recipient list withone request

Authorizations:
ApiKeyAuth
Request Body schema: application/json
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)

Responses

Request samples

Content type
application/json
{
  • "message_body": "hello {{first_name}} {{last_name}} here is {{custom2}} click on link {{shorten_url}}!!",
  • "sender": "My sender",
  • "recipients": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.351626371,
  • "result": [
    ]
}

Continue smart broadcast

Authorizations:
ApiKeyAuth
Request Body schema: application/json
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 sender_ids)

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)

Responses

Request samples

Content type
application/json
{
  • "broadcast_id": 111,
  • "message_body": "sample",
  • "segment_size": 1,
  • "send_now": true,
  • "sender_ids": "1",
  • "utc_offset": 180
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 2.202010018,
  • "result": {
    }
}

Campaign

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

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.

Authorizations:
ApiKeyAuth
Request Body schema: application/json

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

Responses

Request samples

Content type
application/json
{
  • "name": "CampaignName",
  • "start_date": "2020-07-22T21:00:00.000Z",
  • "end_date": "2020-09-25T21:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.044941952,
  • "result": {
    }
}

Get Campaigns

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

Authorizations:
ApiKeyAuth
query Parameters
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

Responses

Request samples 

GET /api/3/Campaign/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012664016,
  • "result": [
    ]
}

Get Campaign by ID

Get Campaign detailes from your MessageWhiz account

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Campaign ID

Responses

Request samples 

GET /api/3/Campaign/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.044941952,
  • "result": {
    }
}

Modify a Campaign

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.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Campaign ID

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "end_date": "2021-03-25T21:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.026245764,
  • "result": {
    }
}

Modify a Campaign

To modify a specific Campaign from your MessageWhiz account, include its ID in the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Campaign ID

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "enabled": "1"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.026245764,
  • "result": {
    }
}

Disable a Campaign

To remove a specific Campaign from your MessageWhiz account, add its ID as parameter to the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Campaign ID

Responses

Request samples 

DELETE /api/3/Campaign/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

DeliveryReport

Get a delivery report

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.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
bid
required
string

id of the broadcast which delivery report should be fetched

Responses

Request samples

Content type
application/json
{
  • "bid": "225544"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.044941952,
  • "result": {
    }
}

Create a Link

Create a Link from your MessageWhiz account

Authorizations:
ApiKeyAuth
Request Body schema: application/json
name
required
string

Link name

url
required
string

Link url itself, in the URI format

object

Links based on detected user platform

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get 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

Authorizations:
ApiKeyAuth
query Parameters
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

Responses

Request samples 

GET /api/3/Link/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{}

Modify a Link

To modify a specific Link, you should specify its ID in the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json
name
required
string

Link name

url
required
string

Link url itself, in the URI format

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.011805652,
  • "result": {}
}

Disable a Link

To remove a specific Link, you should include its ID in the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

DELETE /api/3/Link/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

Monitor link conversion

To receive conversion data from a certain link

Authorizations:
ApiKeyAuth
Request Body schema: application/json
url
required
string

The link to monitor conversion

Responses

Request samples

Content type
application/json
{
  • "url": "messagewhiz.com"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.12326038,
  • "result": {
    }
}

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)

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

Authorizations:
ApiKeyAuth
query Parameters
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.

Request Body schema: multipart/form-data
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:

  • phone_number - required

  • first_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.

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

Responses

Request samples

Content type
multipart/form-data
--form 'doc=@/home/user/Downloads/numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}'\
--form 'name=FirstRecipientList'

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012664016,
  • "result": {
    }
}

Create a Recipient List (manually)

Create a Recipient List by adding the phone numbers manually

Authorizations:
ApiKeyAuth
Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters

Name of the created recipient list

numbers
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "MyRecipientsList",
  • "numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012664016,
  • "result": {
    }
}

Get Recipient Lists

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

Authorizations:
ApiKeyAuth
query Parameters
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

Responses

Request samples 

GET /api/3/RecipientList/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012814664,
  • "result": [
    ]
}

Get Recipients from Recipient List

Get recipients from the specific Recipient List using its ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Recipient List ID

Responses

Request samples 

GET /api/3/RecipientList/{id}/recipients HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012814664,
  • "result": [
    ]
}

Get Numbers from Recipient List

Get an array of phone numbers from the specific Recipient List using its ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Recipient List ID

Responses

Request samples 

GET /api/3/RecipientList/{id}/listNumbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012814664,
  • "result": [
    ]
}

Preview a Recipient List

MessageWhiz API provides you with the possibility to preview your file of contacts before importing it and creating the Recipient List

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
doc
file

An absolute path to the file on your device

Responses

Request samples

Content type
multipart/form-data
--form 'doc=@/home/user/Downloads/numbers_9.csv'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "isAllNum": [
    ],
  • "isExceedLength50": [
    ],
  • "isExceedLength255": [
    ],
  • "isExceedLength5000": [
    ]
}

Download a Recipient List

Download specific Recipient List using its ID and save the response

Authorizations:
ApiKeyAuth
path Parameters
id
required
Array of integers

Sender List ID

Responses

Request samples 

GET /api/3/RecipientList/{id}/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
text/csv
"phone_number";"first_name"
"6593333311";"Anthony"
"6593333322";"Bob"
"6593333333";"Jonathan"
"6593333344";"Alex"

Modify a Recipient List (manually)

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:

PATCH https://sms.messagewhiz.com/api/3/RecipientList/{id}

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Recipient List ID

Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters

Name of the created recipient list

numbers
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "MyRecipientsList",
  • "numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.019542036,
  • "result": {
    }
}

Modify partially a Recipient List

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Recipient List ID

Request Body schema: application/json
name
string [ 1 .. 50 ] characters

Name of the created recipient list

numbers
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "MyRecipientsList",
  • "numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.019542036,
  • "result": {
    }
}

Modify a Recipient List (import a file)

Replace the entire existing Recipient List with the new imported one

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Recipient List ID

Request Body schema: multipart/form-data
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:

  • phone_number - required

  • first_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.

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.

Responses

Request samples

Content type
multipart/form-data
--form 'doc=@/home/user/Downloads/RecipientList.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}'\
--form 'name=FirstRecipientList'

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012664016,
  • "result": {
    }
}

Disable a Recipient List

To remove a specific Recipient List from your MessageWhiz account, you should include its ID the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Recipient List ID

Responses

Request samples 

DELETE /api/3/RecipientList/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

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

Create a Sender from your MessageWhiz account

Authorizations:
ApiKeyAuth
Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$

Sender name

Responses

Request samples

Content type
application/json
{
  • "name": "FirstSender"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.044570548,
  • "result": {
    }
}

Get Senders

Get Senders from your MessageWhiz account

You can include several parameters in your GET query in order to receive only the data you need.

Authorizations:
ApiKeyAuth
query Parameters
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

Responses

Request samples 

GET /api/3/Sender/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.013848856,
  • "result": [
    ]
}

Modify a Sender

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 }

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
Example: 2134

Sender ID

Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$

Sender name

enabled
required
boolean

Make the item active

Responses

Request samples

Content type
application/json
{
  • "name": "FirstSender",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.021960496,
  • "result": {
    }
}

Modify a Sender

If you want to partially update the resource, you can use PATCH

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Sender ID

Request Body schema: application/json
name
string [ 1 .. 50 ] characters ^[^\s]+(\s+[^\s]+)*$

Sender name

enabled
boolean

Make the item active

Responses

Request samples

Content type
application/json
{
  • "name": "FirstSender"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.021960496,
  • "result": {
    }
}

Disable a Sender

To remove a specific Sender from your MessageWhiz account, you should include its ID to the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Sender ID

Responses

Request samples 

DELETE /api/3/Sender/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

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

Create a Sender List from your MessageWhiz account

Authorizations:
ApiKeyAuth
Request Body schema: application/json

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

Responses

Request samples

Content type
application/json
{
  • "name": "FirstSenderList",
  • "senderIds": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012814664,
  • "result": {
    }
}

Get Sender List

Get Sender Lists from your MessageWhiz account

Authorizations:
ApiKeyAuth
query Parameters
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

Responses

Request samples 

GET /api/3/SenderList/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.00982226,
  • "result": [
    ]
}

Modify a Sender List

To modify a specific Sender List by adding new Senders and changing the list name, add its ID to the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json
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

true to make the item active or false

Responses

Request samples

Content type
application/json
{
  • "name": "FirstSenderList",
  • "senderIds": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.040806108,
  • "result": {
    }
}

Modify a Sender List partially

To modify a specific Sender List by adding new Senders and changing the list name, add its ID to the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Senders List ID

Request Body schema: application/json
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

true to make the item active or false

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.009910892,
  • "result": {
    }
}

Disable a Sender List

To remove a specific Sender List from your MessageWhiz account, you should include its ID the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

DELETE /api/3/SenderList/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

Add Senders to a Sender List

To add Senders to a Sender List from your MessageWhiz account, specify Sender List ID

Authorizations:
ApiKeyAuth
query Parameters
listID
required
integer

Senders ids

Request Body schema: application/json
ids
Array of integers

An array of Sender Ids

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.032248508,
  • "result": [
    ]
}

Get Senders from the List

Get an array of Sender objects from a specific Sender List

Authorizations:
ApiKeyAuth
query Parameters
listID
required
integer

Senders ids

Responses

Request samples 

GET /api/3/SenderList/{listID}/senders HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.008722612,
  • "result": {
    }
}

Disable a Sender in the Sender List

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}

Authorizations:
ApiKeyAuth
query Parameters
listID
required
integer

Senders ids

Responses

Request samples 

DELETE /api/3/SenderList/{listID}/senders HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

Template

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

Create a Template from your MessageWhiz account

Authorizations:
ApiKeyAuth
Request Body schema: application/json
body
required
string

A text body of the message Template

name
required
string

Template name

Responses

Request samples

Content type
application/json
{
  • "name": "FirstTemplate",
  • "body": "HI!"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.014043792,
  • "result": {
    }
}

Get Templates

Get Templates from your MessageWhiz account

Authorizations:
ApiKeyAuth
query Parameters
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:

?filter={parameter_name}={parameter_value},{parameter_name}...

enabled
boolean

Fetch only active items

Responses

Request samples 

GET /api/3/Template/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.007669944,
  • "result": [
    ]
}

Modify a Template

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.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json
body
string

A text body of the message Template

name
string

Template name

Responses

Request samples

Content type
application/json
{
  • "name": "AnotherTemplateName",
  • "body": "HI!"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.019078568,
  • "result": {
    }
}

Disable a Template

To remove a specific Template from your MessageWhiz account, include its ID in the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

DELETE /api/3/Template/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

Trigger

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

Create a Trigger from your MessageWhiz account:

Authorizations:
ApiKeyAuth
Request Body schema: application/json

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

Responses

Request samples

Content type
application/json
{
  • "name": "newTrigger"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.116146556,
  • "result": {
    }
}

Get Trigger

Get Trigger from your MessageWhiz account

You can include several parameters to your GET query in order to receive only the data you need

Authorizations:
ApiKeyAuth
query Parameters
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

Responses

Request samples 

GET /api/3/Trigger/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.007109016,
  • "result": [
    ]
}

Modify a Trigger

To modify a specific Trigger, include its ID in the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json

In the request body specify the new value of name, for instance:

{ "name":"#" }

name
required
string

Trigger name

Responses

Request samples

Content type
application/json
{
  • "name": "#"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.019078568,
  • "result": {
    }
}

Disable a Trigger

To remove a specific Template from your MessageWhiz account, include its ID in the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

DELETE /api/3/Trigger/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

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

Create a Word Spinner from your MessageWhiz account

Authorizations:
ApiKeyAuth
Request Body schema: application/json
name
required
string

Word Spinner name

words
required
Array of strings

An array of word synonyms

Responses

Request samples

Content type
application/json
{
  • "name": "Fit32",
  • "words": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.041090464,
  • "result": {
    }
}

Get Word Spinners

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

Authorizations:
ApiKeyAuth
query Parameters
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:

?filter={parameter_name}={parameter_value},{parameter_name}...

enabled
boolean

Fetch only active items

Responses

Request samples 

GET /api/3/Spinner/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.008722612,
  • "result": [
    ]
}

Modify a Word Spinner

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.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json
name
required
string

Word Spinner name

words
required
Array of strings

An array of word synonyms

Responses

Request samples

Content type
application/json
{
  • "name": "Fit32",
  • "words": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.014242532,
  • "result": {
    }
}

Modify a Word Spinner

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

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json
name
string

Word Spinner name

words
Array of strings

An array of word synonyms

enabled
boolean

Set sinner active

Responses

Request samples

Content type
application/json
{
  • "enabled": "0"
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.0242746,
  • "result": {
    }
}

Disable a Word Spinner

To remove a specific Word Spinner from your MessageWhiz account, include its ID in the query

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

DELETE /api/3/Spinner/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

Unsubscribe List

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 (import a file)

Create an Unsubscribe List by importing file of contacts

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
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:

  • phone_number - required
  • first_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
required
file

An absolute path to the file on your device

Responses

Request samples

Content type
multipart/form-data
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}' \
--form 'name=FirstRecipientList'

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.025868544,
  • "result": {
    }
}

Create an Unsubscribe List (manually)

Create an Unsubscribe List from your MessageWhiz account

Authorizations:
ApiKeyAuth
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "name": "FirstUnsubscribeList",
  • "numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.025868544,
  • "result": {
    }
}

Get Unsubscribe Lists

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

Authorizations:
ApiKeyAuth
query Parameters
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:

?filter={parameter_name}={parameter_value},{parameter_name}...

start
integer >= 0
Default: 0
Example: start=0

The number of items to skip

Responses

Request samples 

GET /api/3/UnsubscribeList/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.028108664,
  • "result": [
    ]
}

Modify an Unsubscribe List (import a file)

Replace the entire existing Unsubscribe List with the new imported one

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: multipart/form-data

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:

  • phone_number - required
  • first_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.

Responses

Request samples

Content type
multipart/form-data
--form 'mapping={"0":"phone_number"}' \
--form 'doc=@/home/user/Downloads/UnsubscribeList.csv'

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.040112328,
  • "result": {
    }
}

Modify an Unsubscribe List

Replace the entire existing Unsubscribe List with the new imported one

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json

You can disable an unsubscribe list by entering "enabled": false in the request body.

enabled
required
any

true set item active, false - exclude for searches, submits and other activities

Responses

Request samples

Content type
application/json
{
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.022112432,
  • "result": {
    }
}

Disable a Unsubscribe List

To remove a specific Sender List from your MessageWhiz account, you should include its ID in the path

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

DELETE /api/3/UnsubscribeList/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.012125844,
  • "result": true
}

Preview an Unsubscribe List

MessageWhiz API provides you with the possibility to preview your file of contacts before actually importing it and to create the Unsubscribe List

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
doc
required
file

An absolute path to the file on your device

Responses

Request samples

Content type
multipart/form-data
--form 'doc=@/home/user/Downloads/numbers_9.csv'

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.008022008,
  • "result": {
    }
}

Download an Unsubscribe List

Download a specific Unsubscribe List using its ID and then save the response

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

GET /api/3/UnsubscribeList/{id}/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
text/csv
"phone_number"
"380502327265"
"380502222233"
"380643333322"

Add Numbers to Unsubscribe List

Add phone numbers to the existing Unsubscribe List (include its ID in the query)

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Request Body schema: application/json
numbers
required
Array of integers unique
Default: []

Array of phone numbers that the Unsubscribe List consists of

Responses

Request samples

Content type
application/json
{
  • "numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.031270908,
  • "result": {
    }
}

Get Numbers from Unsubscribe List

Get phone numbers from the specific Unsubscribe List using its ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Item ID

Responses

Request samples 

GET /api/3/UnsubscribeList/{id}/members HTTP/1.1
Host: sms.messagewhiz.com
apikey: YOUR_COMPANY_API_KEY

Response samples

Content type
application/json
{
  • "errorCode": 0,
  • "errorMessage": "",
  • "errorType": "",
  • "executionTime": 0.018904092,
  • "result": [
    ]
}

Messages

Send a message to the given channel.

Send a Message

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Send a Message.

One of
One of
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 in this field

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 sms in this field

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "message_type": "text",
  • "text": "Hey! this is my awesome message!",
  • "to": "447700900000",
  • "from": "b38c2869-af85-4a00-8552-51b53667fa11",
  • "channel": "sms"
}

Response samples

Content type
application/json
{
  • "message_uuid": "b38c2869-af85-4a00-8552-51b53667fa11"
}

Callback payload samples

Callback
Content type
application/json
Example
{
  • "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": {
    },
  • "client_ref": "string",
  • "channel": "sms"
}

Webhooks

Set webhook for inbound messages

Webhook for an inbound message from a customer to you.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
One of
inboundMessageUrl
required
string

Webhook url.

agentID
required
string

The Agent ID used as the sender's phone number

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Request is successful"
}

Customers

Create customer

Create customer. If the customer create is successful, you will receive a response status of 200.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
phone
required
string [ 3 .. 15 ] characters ^[0-9]+$

The phone number of the customer

name
string <= 32 characters

The name of the customer

Responses

Request samples

Content type
application/json
{
  • "phone": "145044111206"
}

Response samples

Content type
application/json
{
  • "id": "76fdcf10-2352-4da1-ab84-4b1f7ddf8cbd",
  • "chatbot_enabled": {
    },
  • "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 customers

Get a list of customers with customers data.

Authorizations:
ApiKeyAuth
query Parameters
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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get customer

Retrieve customer data by providing either the customer ID or the customer phone number.

Authorizations:
ApiKeyAuth
path Parameters
customer_id or phone
required
string

Customer ID or customer phone

Responses

Response samples

Content type
application/json
{
  • "id": "76fdcf10-2352-4da1-ab84-4b1f7ddf8cbd",
  • "chatbot_enabled": {
    },
  • "phone": "145044111206",
  • "name": "John Smith",
  • "country": "US",
  • "subscriptions": {
    },
  • "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

Update customer. If the customer update is successful, you will receive a response status of 204.

Authorizations:
ApiKeyAuth
path Parameters
customer_id
required
string

Customer ID

Request Body schema: application/json
required
object

Whether chatbot is enabled for conversations with current customer

name
string <= 32 characters

The name of the customer

Responses

Request samples

Content type
application/json
{
  • "name": "CustomerName"
}

Response samples

Content type
application/json
{}

Delete customer

Delete customer. If the customer delete is successful, you will receive a response status of 204.

Authorizations:
ApiKeyAuth
path Parameters
customer_id
required
string

Customer ID

Responses

Response samples

Content type
application/json
{}