Introduction

Using the MessageWhiz API, you can create message campaigns, send individual SMS messages or entire message broadcasts, manage recipients, senders, unsubscribers lists, and create and manage templates, tokens and links.

This document will guide you through the core endpoints and functionality of the Message Whiz API, so you can quickly and efficiently start your messaging.

Getting started

In this section, we describe all the necessary steps to send your first broadcast via the MW API.

To start, MessageWhiz uses API keys to allow access to the API. You can find your API key in your personal MW account page.

To properly access the MessageWhiz platform, the API key needs to be included in the header for all API requests to the server.

Sending First Broadcast

In order to send the basic message broadcast, you need to perform the following steps:

• Create a Campaign - a set of SMS messages grouped under one campaign name.
• Create Recipient List - phone numbers to which the messages will be sent.
• Create Sender - a number, name, or ID that recipients see on their devices when they receive a message from you. Only after creating these entities, you can create and send a broadcast. Or you might use already existing entities for broadcasting as well.

Generic replaceable

The following variables should be replaced with your actual information in requests:

Campaigns

A Campaign unifies a set of SMS messages grouped under one campaign name. The campaign exists in a specified time period, thus start and end dates should be indicated during campaign creation.

Create a Campaign

Example Request

POST /api/3/campaign HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "name":"CampaignName",
    "start_date":"2020-07-22T21:00:00.000Z",
    "end_date":"2020-09-25T21:00:00.000Z"
}

Example Response (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.044941952,
   "result": {
       "id": 46279,
       "is_default": 0,
       "name": "CampaignName",
       "start_date": "2020-07-22T21:00:00.000Z",
       "end_date": "2020-09-25T21:00:00.000Z",
       "enabled": true
   }
}

Create a Campaign from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/campaign

Request Body

In the request body specify details for the Campaign that will be created.

Required parameters:

• name(string) - Campaign name

Optional parameters:

• start_date(string) - Campaign start date,
• end_date(string) - Campaign end date.

Date and time are expressed according to ISO 8601.

Get Campaigns

Request Example

GET /api/3/campaign?start=0 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

Response Example (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.012664016,
   "result": [
       {
           "enabled": true,
           "id": 46279,
           "is_default": 0,
           "name": "CampaignName",
           "start_date": "2020-07-22T21:00:00.000Z",
           "end_date": "2020-09-25T21:00:00.000Z",
           "userList": [
               {
                   "campaign_id": 46279,
                   "user_id": 3191,
                   "company_id": 3182
               }
           ]
       },
       {
           "enabled": true,
           "id": 34641,
           "is_default": 1,
           "name": "Default campaign",
           "start_date": null,
           "end_date": null,
           "userList": [
               {
                   "campaign_id": 34641,
                   "user_id": 3191,
                   "company_id": null
               }
           ]
       }
   ]
}

Get Campaigns from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/campaign

Query Parameters

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

As an example, to get first two inactive campaigns, the query URL will be the following:

GET https://sms.messagewhiz.com/api/3/campaign?limit=2&enabled=false

To get the Campaign by the name:

GET https://sms.messagewhiz.com/api/3/campaign?filter=name=CampaignName

Modify a Campaign

PUT Request Example

PUT /api/3/campaign/46279 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "end_date":"2021-03-25T21:00:00.000Z"
}

Response Example (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.026245764,
   "result": {
       "id": 46279,
       "is_default": 0,
       "name": "CampaignName",
       "start_date": "2020-07-22T21:00:00.000Z",
       "end_date": "2021-03-25T21:00:00.000Z",
       "enabled": true
   }
}

PATCH Request Example

PATCH /api/3/campaign/46279 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": "1"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.013305616,
    "result": {
        "id": 46279,
        "enabled": 1
    }
}

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

PUT https://sms.messagewhiz.com/api/3/campaign/{id}

For instance, PUT https://sms.messagewhiz.com/api/3/campaign/46279, where 46279 is the ID of the Campaign that will be replaced using the data presented in the request body.

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

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

Request Body

In the request body specify the value you want to modify, for instance:

{ "end_date":"2021-03-25T21:00:00.000Z" }

Disable a Campaign

Request Example

DELETE /api/3/campaign/46317 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.034133648,
   "result": true
}

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

DELETE https://sms.messagewhiz.com/api/3/campaign/{id}

Recipients

Here you can manage your recipients - basically phone numbers grouped into lists of recipients to whom the messages will be sent. Some additional metadata related to each recipient might be included in the recipient lists and used in the broadcasts.

You have two options for the recipient list creation:

• Import .xlsx, .xls, or .csv file with numbers and metadata(optional),
• Add numbers manually in array.

Please make sure to enter the number in the international format, including the country code. For example, enter 18756785619 if you are sending an SMS to a recipient from the USA or Canada, where 1 is the country code.

Create a Recipient List (import a file)

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/RecipientList?truncate=true' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}' \
--form 'name=FirstRecipientList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.032846168,
    "result": {
        "inserted": 4,
        "total": 4,
        "wrong": 0,
        "duplicate": 0,
        "recipient_list_id": 267628
    }
}

Create a Recipient List by importing file of contacts:

POST https://sms.messagewhiz.com/api/3/RecipientList?truncate=true

Request Body

In the request body, specify the Recipient List details:

• name - name of the Recipient List.

• mapping - the markers to specify the type of stored data in the columns. Possible markers:

  • phone_number - 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 - an absolute path to the file on your device

(e.g /Users/userName/dir/recipients.csv).

Query Parameters

first_name, last_name - max length is 50 symbols, email, url - 255, other - 5000.

if truncate===false and there are fields in the list that exceed the limits, an error while loading occurs.

To check if your file fits, you can preview it.

Create a Recipient List (manually)

Request Example

POST /api/3/recipientList/numbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "name": "ManuallyAddedList",
    "numbers": ["380503327227", "380848122639"]
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.018502512,
    "result": {
        "inserted": 2,
        "wrong": 0,
        "duplicate": 0,
        "total": 2,
        "recipient_list_id": 267888,
        "count": 2
    }
}

Create a Recipient List by adding the phone numbers manually:

POST https://sms.messagewhiz.com/api/3/recipientList/numbers

Request Body

In the request body, specify the Recipient List details:

• name - name of the created recipient list,
• numbers - array of numbers to create a recipient list.

Preview a Recipient List

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/recipientList/1/preview' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' 

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.00777864,
    "result": {
        "data": [
            [
                "phone_number",
                "first_name"
            ],
            [
                "6593333311",
                "Anthony"
            ],
            [
                "6593333322",
                "Bob"
            ],
            [
                "6593333333",
                "Jonathan"
            ],
            [
                "6593333344",
                "Alex"
            ]
        ],
        "isAllNum": [
            true,
            false
        ],
        "isExceedLength50": [
            false,
            false
        ],
        "isExceedLength255": [
            false,
            false
        ],
        "isExceedLength5000": [
            false,
            false
        ]
    }
}

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

POST https://sms.messagewhiz.com/api/3/recipientList/6/preview

Request Body

In the request body, you should specify:

• doc - an absolute path to the file on your device
  

Get Recipient Lists

Request Example

GET /api/3/RecipientList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.012814664,
    "result": [
        {
            "id": 267891,
            "name": "SecondRecipientList",
            "enabled": 1,
            "count": 4
        },
        {
            "id": 267888,
            "name": "ManuallyAddedList",
            "enabled": 1,
            "count": 2
        },
        {
            "id": 267628,
            "name": "FirstRecipientList",
            "enabled": 1,
            "count": 4
        },
        {
            "id": 222345,
            "name": "ev",
            "enabled": 1,
            "count": 1
        }
    ]
}

Get Recipient Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/RecipientList

Query Parameters

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

For example, to get only the Recipient List with specific name(e.g SecondRecipientList), use the following query:

https://sms.messagewhiz.com/api/3/RecipientList?filter=name=SecondRecipientList

Get Recipients from Recipient List

Request Example

GET /api/3/recipientList/267628/recipients HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008162772,
    "result": [
        {
            "phone_number": 6593333311,
            "first_name": "Anthony"
        },
        {
            "phone_number": 6593333322,
            "first_name": "Bob"
        },
        {
            "phone_number": 6593333333,
            "first_name": "Jonathan"
        },
        {
            "phone_number": 6593333344,
            "first_name": "Alex"
        }
    ]
}

Get recipients from the specific Recipient List using its ID:

GET https://sms.messagewhiz.com/api/3/recipientList/{id}/recipients

The response contains an object for each recipient in the list, including their metadata (first_name, last_name,email, url, custom).

Get Numbers from Recipient List

Request Example

GET /api/3/recipientList/267628/listNumbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008841536,
    "result": [
        "6593333311",
        "6593333322",
        "6593333333",
        "6593333344"
    ]
}

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

GET https://sms.messagewhiz.com/api/3/recipientList/{id}/listNumbers

Download a Recipient List

Request Example

GET /api/3/recipientList/267628/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

"phone_number";"first_name"
"6593333311";"Anthony"
"6593333322";"Bob"
"6593333333";"Jonathan"
"6593333344";"Alex"

Download specific Recipient List using its ID and save the response:

GET https://sms.messagewhiz.com/api/3/recipientList/267628/download

Modify a Recipient List (manually)

PUT Request Example

PUT /api/3/recipientList/267891/numbers HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "name": "Mw-manual",
    "numbers": ["380503322227"]
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.019542036,
    "result": {
        "inserted": 1,
        "wrong": 0,
        "duplicate": 0,
        "total": 1,
        "recipient_list_id": 267891,
        "count": 5
    }
}

PATCH Request Example

PATCH /api/3/RecipientList/267891 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "name": "EditingList",
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.031447856,
    "result": {
        "name": "EditingList",
        "enabled": true,
        "count": 5
    }
}

To modify a specific Recipient List by adding new numbers manually or changing the list name, add its ID to the query:

PUT https://sms.messagewhiz.com/api/3/recipientList/{id}/numbers

In the request body specify the new values for this list:

• name(string) - name of the list, by specifying this value you can change Recipient List name,
• numbers(array) - array of numbers that will be added to the list.

If you want to just partially update the resource(by changing the list name), you can use:

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

Modify a Recipient List (import a file)

PUT Request Example

curl --location --request PUT 'https://sms.messagewhiz.com/api/3/recipientList/267891' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/RecipientList.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name", "2":"last_name"}' \
--form 'name=NewList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.027778432,
    "result": {
        "inserted": 4,
        "total": 4,
        "wrong": 0,
        "duplicate": 0,
        "recipient_list_id": 267891
    }
}

Replace the entire existing Recipient List with the new imported one:

PUT https://sms.messagewhiz.com/api/3/recipientList/{id}

Request Body

In the request body specify the new values for this list:

• name - name of the new recipient list.

• mapping - the markers to specify the type of stored data in the columns.

(e.g {"0":"phone_number", "1":"first_name", "2":"last_name"}).

The mapping structure should correspond to the structure presented in the new uploaded file.

• doc - an absolute path to the file on your device

Disable a Recipient List

Request Example

DELETE /api/3/RecipientList/267891 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.011510284,
    "result": true
}

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

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

Senders

Sender is generally a number, name, or ID that recipients see on their devices when they receive a message from you. Here's how to manage a single sender entity.

Create a Sender

Example Request

POST /api/3/sender HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name": "FirstSender"
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.044570548,
    "result": {
        "id": 28938892,
        "name": "FirstSender",
        "enabled": true
    }
}

Create a Sender from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/sender

Request Body

In the request body only specify a name of the Sender that will be created,

e.g. "name": "FirstSender"

Get Senders

Request Example

GET /api/3/sender? HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.013848856,
    "result": [
        {
            "enabled": true,
            "id": 28938892,
            "name": "FirstSender"
        },
        {
            "enabled": true,
            "id": 28905672,
            "name": "test"
        }
    ]
}

Get Senders from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/sender

Query Parameters

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

Modify a Sender

PUT Request Example

PUT /api/3/sender/28905672 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
   "name": "TestSender"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.021960496,
    "result": {
        "id": 28905672,
        "name": "TestSender",
        "enabled": true
    }
}

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

PUT https://sms.messagewhiz.com/api/3/sender/{id}

Request Body

In the request body specify the new sender name and status for the selected Sender entity, for instance:

{ "name": "TestSender", "enabled": 0 }

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

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

Request Body

In the request body specify the new Sender status, for instance:

{ "enabled": 0 }

Disable a Sender

Request Example

DELETE /api/3/sender/28938891 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.012125844,
    "result": true
}

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

DELETE https://sms.messagewhiz.com/api/3/sender/{id}

Sender Lists

MessageWhiz provides you with the possibility to group multiple Senders into one Sender List,
from which a Sender will be randomly select for each broadcast message.

Create a Sender List

Example Request

POST /api/3/senderList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name":"FirstSenderList",
    "senderIds": [28938892, 28905674]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.046940544,
    "result": {
        "id": 5456,
        "name": "FirstSenderList",
        "enabled": true,
        "count": 2
    }
}

Create a Sender List from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/senderList

Request Body

In the request body specify the following:

• name(string) - Sender List name
• senderIds(array) - an array of IDs of the Senders that the list will consist of

In case of all invalid senderIds, Senders will not be added to the list, and the list will be created empty.

Add Senders to a Sender List

Example Request

POST  /api/3/senderList/5456/senders HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "ids": [28899614, 28899615]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.032248508,
    "result": [
        28899614, 28899615
    ]
}

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

POST https://sms.messagewhiz.com/api/3/senderList/{listId}/senders

Request Body

In the request body specify an array of Sender Ids "ids": [,] that will be added to the list.

Get Sender Lists

Request Example

GET /api/3/senderList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.00982226,
    "result": [
        {
            "enabled": true,
            "id": 5456,
            "name": "FirstSenderList",
            "count": 2
        },
        {
            "enabled": true,
            "id": 5455,
            "name": "SenderList",
            "count": 1
        }
    ]
}

Get Sender Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/senderList

Query Parameters

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

Get Senders from the List

Request Example

GET /api/3/senderList/5456/senders HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008722612,
    "result": {
        "id": 5456,
        "senders": [
            {
                "senderId": 28905674,
                "name": "test2"
            },
            {
                "senderId": 28938892,
                "name": "FirstSender"
            }
        ]
    }
}

Get an array of Sender objects from a specific Sender List:

GET https://sms.messagewhiz.com/api/3/senderList/{id}/senders

Modify a Sender List

PUT Request Example

GET /api/3/senderList/5456 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
{
    "name": "New",
    "senderIds": [28938892, 28905674]
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.040806108,
    "result": {
        "id": 5456,
        "name": "New",
        "enabled": true,
        "count": 2
    }
}

PATCH Request Example

PATCH /api/3/senderList/5456 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": true,
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.009910892,
    "result": {
        "id": 5456,
        "enabled": 1
    }
}

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

PUT https://sms.messagewhiz.com/api/3/sendertList/{id}

In the request body specify the new values for this list:

• name(string) - name of the list, by specifying this value you can change Sender List name,
• senderIds(array) - array of Sender Ids that will be added to the list.
• enabled(bool) - true or false

If you want to just partially update the resource(by enabling or disabling it), you can use:

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

Disable a Sender List

Request Example

DELETE /api/3/senderList/5457 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.017833028,
    "result": true
}

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

DELETE https://sms.messagewhiz.com/api/3/senderList/{id}

Disable a Sender in the Sender List

Request Example

DELETE /api/3/senderList/5456/senders?id=28905674 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.013993384,
    "result": true
}

To remove a Sender from the Sender List, you should include Sender List ID in the query and specify Sender ID as required parameter:

DELETE https://sms.messagewhiz.com/api/3/senderList/{listID}/senders?id={senderID}

Send a Broadcast

Estimate Broadcast

Example Request

POST /api/3/Broadcast/estimate HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "broadcast_type": 11,
    "recipient_list_ids": "288696",
    "unsubscriber_list_ids": "",
    "message_body": "sample"
}

Example Response

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 5.076538867,
    "result": {
        "messages": 1,
        "sum": 3.36,
        "parts": 1,
        "recipient_id_map": [],
        "replacements": {},
        "firstSegmentCount": 1,
        "recipient_meta_data_map": [
            [
                3852004823,
                {
                    "phone_number": 3852004823,
                    "email": "email@gmail.com",
                    "custom": "Custom",
                    "url": "https://google.com",
                    "first_name": "John",
                    "last_name": "Doe"
                }
            ]
        ],
        "recipients": {
            "3852004823": {
                "rate": 3.36,
                "mccMnc": 111222
            }
        },
        "messageExpanded": {
            "actions": {
                "callback": {
                    "replacement": "",
                    "uuid": "",
                    "count": 0
                },
                "first_name": {
                    "replacement": "",
                    "count": 0
                },
                "last_name": {
                    "replacement": "",
                    "count": 0
                },
                "url": {
                    "replacement": "",
                    "count": 0
                },
                "random_symbol": {
                    "replacement": "h",
                    "count": 0
                },
                "verification_code": {
                    "replacement": "",
                    "count": 0
                },
                "custom": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom1": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom2": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom3": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom4": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "gender": {
                    "replacement": "",
                    "count": 0
                },
                "word_spinner": {
                    "replacement": "",
                    "count": 0,
                    "parameters": [],
                    "isApproximate": true
                },
                "link": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "link_list": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "unsubscription_link": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "shorten_url": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "callback_link": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                }
            },
            "text": "sample"
        },
        "links": {},
        "warnings": [],
        "estimateHash": "8572aeb3624293a238cd2d7cd901fb61743e3a435e50e00d631a410cb0044d39dd4a53be35e040974f88c7e3799ab1f8d1629455c260a87b0fa48da547c7ffcb",
        "batchEstimation": {
            "messages": 1,
            "sum": 3.36,
            "parts": 1
        }
    }
}

To Estimate a broadcast via API:

POST sms.messagewhiz.com/api/3/Broadcast/estimate

Request Parameters

Required:

• recipient_list_ids (string) - ids of the recipient lists (comma separated numbers)
• message_body (string) - body of the message

Optional:

• template_id (number) - id of the message template (may be used instead of message_body)
• unsubscriber_list_ids (string) - ids of the unsubscriber lists (comma separated numbers)
• recipient (number) - recipients' number (may be used instead of recipient_list_ids)
• eb_type (string) - specifies which type of smart broadcast will be sent (CTR or manual)
• first_segment_size (number) - count of the recipients whose messages will be sent within the first (current if eb_type is manual) segment (available only when eb_type is specified)
• template_ids (string) - ids of the templates that will be used (available only if eb_type is set to manual; may be used instead of message_body; comma separated numbers)
• next_segment_size (number) - count of the recipients whose messages will be sent within the next segments of a CTR Threshold broadcast (available only when eb_type is set to CTR)
• recipient_cap (number) - count of recipients whose messages will be sent before the broadcast will be paused for further actions (available only when eb_type is set to CTR)

Fast Single

Example Request

POST /sms HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json

{
    "api_key": <apikey>,
    "to": "2605876689",
    "from": "sender",
    "text": "sample message"
}

Example Response

{
  "message_id": "rbzAV2NXxJ_u5bDL35Hop"
}

Example DLR Callback

{
  "message_id": "rbzAV2NXxJ_u5bDL35Hop",
  "sender": "sender",
  "recipient": "5417543010",
  "content": "Message Text",
  "state": 2,
  "status": "DELIVRD",
  "client_ref": "Custom param",
  "timestamp": "2023-03-28T15:52:31.279Z",
  "parts_count": 1,
  "price": 2,
  "parts": [
    {
      "pdu_id": "SVV7oRyvMLX1OIzLwta2p",
      "encoding": 0,
      "content": "Message Text",
      "status": "DELIVRD"
    }
  ]
}

Example link click Callback

{
  "message_id": "4iE_yS65Vn8iXCqaW5L2N",
  "link_id": "hkzt.me/ZPFuT5",
  "time": "2023-05-01T13:46:37.921Z",
  "unique_click": true
}

Error codes/Validation errors:

without mandatory field "text":

{
  "statusCode": 400,
  "message": [
    "text must be shorter than or equal to 100000 characters",
    "text must be longer than or equal to 1 characters",
    "text should not be empty"
  ],
  "error": "Bad Request"
}

without mandatory field "to":

{
  "statusCode": 400,
  "message": [
    "The recipient number entered is invalid. Please ensure that the number is between 10 and 15 digits in length."
  ],
  "error": "Bad Request"
}

without mandatory field "from":

{
  "statusCode": 400,
  "message": [
    "Sender must not exceed 11 letters (latin alphabet or special symbols “'._-+&{space}” are allowed) or 20 numbers."
  ],
  "error": "Bad Request"
}

without mandatory field "api_key":

{
  "statusCode": 401,
  "message": "Unauthorized"
}

To send a single message from your MessageWhiz account:

POST https://sms.messagewhiz.com/sms

Request Body

Required parameters:

• api_key - an API key of your account
• from - provide here the Sender name
• to - phone number of the recipient
• text - text of the message that the recipient will see; can contain text and links.

Optional parameters:

• client_ref - custom parameter up to 160 characters, will be present in response for Single creation, DLR to Webhook and callback
• callback - the URL of callback to which DLR statuses per single message will be sent

Initial HTTP Response

• message_id - the ID of the message

Response on DLR callback

When a single message was sent, we got a response with information about the sent message and DLR status.

Parameters:

• message_id - the ID of the message
• sender - the Sender name that was used in message
• recipient - phone number of the recipient
• content - text of the message that the recipient received
• state - the id of DLR status of message
• status - the DLR status of single message. Possible DLR statuses (with their ids):
  • 1 - ENROUTE
  • 2 -DELIVRD
  • 3 - EXPIRED
  • 4 - DELETED
  • 5 - UNDELIV
  • 6 - ACCEPTD
  • 7 - UNKNOWN
  • 8 - REJECTD
  • 9 - FAILED
• client_ref - custom parameter up to 160 characters, will be present in response for Single creation, DLR to Webhook and callback
• timestamp - time of sending message
• parts_count - the amount of PDUs in the message
• price - the cost of single message
• parts - information about every PDU, may have such fields:
  • pdu_id - ID of the message part
  • encoding - text encoding used for the message part
  • content - text of the message part
  • status DLR status code for the message part

Response on link click callback

After the user’s click on the link, an additional response with the click info appears.

Parameters:

• message_id - the ID of the message
• link_id - the link that was assigned and clicked by the user
• unique_click - identifies that this is a unique click
• time - time of clicking the link

Send a Tiny single (OLD)

Example Request

POST /api/3/Broadcast/tiny/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "recipient": "2605876689",
    "sender": "sender",
    "message_body": "sample message"
}

Example Response (200)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.049512918,
    "result": {
        "broadcastId": 1174181,
        "segmentId": 523940
    }
}

To send a tiny single message from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast/tiny/

Request Body

In the request body, the following single message components can be used.

Required parameters:

• recipient (string) - phone number of the Recipient,
• sender (string) - name of the Sender,
• message_body - text of the message that recipient will see; can contain only text.

Send a Single message (OLD)

Example Request

POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "name":"Single SMS to 380681337228",
 "campaign_id":1,
 "broadcast_type":10,
 "unsubscriber_list_ids":"",
 "sender_id":"23",
 "recipient":"380681337228",
 "message_body":"message body",
 "custom_parameter":"1234abcd5678efgh"
}

Example Response (200 OK)

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":0.160202353,
  "result": {
    "broadcastID":331,
    "segmentID":493,
    "custom_parameter":"1234abcd5678efgh"
  }
}

To send a single message from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast

Request Body

In the request body, the following single message components can be used.

Required parameters:

• campaign_id - an ID of a previously created active Campaign,
• broadcast_type (int) - type of the broadcast, for single type the value is 10 (10 - single, 11 - base, 12 - smart),
• recipient (string) - phone number of the recipient,
• sender_id(int) - ID of a previously created Sender.
• message_body - text of the message that the recipient will see; can contain text, links, and tokens.

Optional parameters:

• unsubscriber_list_ids (string) - IDs of previously created Unsubscribe Lists,
• send_date (string) - specific date and time for sending a message (e.g."2020-07-31T14:25:49.614Z"),
• utc_offset - specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0),
• trigger_id - id of the trigger,
• delay - the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,
• template_id - id of the message template, if you want to use a specific template for message body,
• custom_parameter - custom parameter up to 40 characters, will be present in responce for Single creation and DLR to Webhook

Send a Base Broadcast

Example Request

POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "name":"broadcast",
 "campaign_id":1,
 "broadcast_type":11,
 "unsubscriber_list_ids":"",
 "sender_ids":"23",
 "recipient_list_ids":"12",
 "message_body":"broadcast message",
}

Example Response (200 OK)

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":0.446636071,
  "result": {
    "broadcastID":333,
    "segmentID":494
  }
}

To send a Basic Broadcast from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast

Request Body

In the request body, the following broadcast components can be used.

Required parameters:

• campaign_id - an ID of a previously created active Campaign,
• broadcast_type - type of broadcast, for base broadcast type the value is 11 (10 - single, 11 - base, 12 - smart),
• name - broadcast name,
• sender_ids (string) - IDs of previously created Senders,
• recipient_list_ids (string) - IDs of previously created Recipient Lists,
• message_body - text of the message that the recipient will see; can contain text, links, and tokens.

Optional parameters:

• sender_list_ids (string) - IDs of previously created Sender Lists,
• unsubscriber_list_ids (string) - IDs of previously created Unsubscribe Lists,
• send_date (string) - specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z"),
• utc_offset (int) - specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0),
• trigger_id - id of the trigger,
• delay - the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,
• template_id - id of the message template, if you want to use a specific template for message body.

Send a Smart Broadcast

Example Request

POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "name":"manual",
 "campaign_id":1,
  "broadcast_type":12,
 "unsubscriber_list_ids":"",
 "sender_ids":"23",
 "recipient_list_ids":"12",
 "message_body":"man message",
 "send_date":"2021-03-01T12:41:38.837Z",
 "utc_offset":120,
 "eb_type":"manual",
 "first_segment_size":"3",
}

Example Response (200 OK)

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":0.446636071,
  "result": {
    "broadcastID":333,
    "segmentID":495
  }
}

To send a Smart Broadcast from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast

In the request body, the following broadcast components can be used.

Required parameters:

• campaign_id - an ID of a previously created active Campaign,
• broadcast_type - type of broadcast, for smart broadcast type the value is 12 (10 - single, 11 - base, 12 - smart),
• name - broadcast name,
• eb_type (sting) - type of smart broadcast, can be either 'CTR' or 'manual',
• sender_ids (string) - IDs of previously created Senders,
• recipient_list_ids(string) - IDs of previously created Recipient Lists,
• message_body - text of the message that the recipient will see; can contain text, links, and tokens.

To send the Manual Smart Broadcast add the following parameters.

Required parameters:

• first_segment_size (int) - the size of the segment

Optional parameters:

• sender_list_ids (string) - IDs of previously created Sender Lists,
• unsubscriber_list_ids(string) - IDs of previously created Unsubscribe Lists,
• send_date(string) - specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z"),
• utc_offset - specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0),
• trigger_id - id of the trigger,
• delay - the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,
• template_id - id of the message template, if you want to use a specific template for message body,
• template_ids(string) - IDs of the message templates, if you want to use a specific templates for message body,

To send the CTR Threshold Smart Broadcast add the following parameters.

Required parameters:

• exp_date (date) - the date when the broadcasts will expire (e.g. "2021-09-25 13:55:58"),
• conversion_threshold (int) - upon reaching this conversion rate, the next segment will be sent (e.g. value 50 means 50% conversion)
• first_segment_size (int) - the size of the first segment (for 'CTR' type),
• next_segment_size (int) - the size of the next segments in CTR broadcast (for 'CTR' type),
• recipeint_cap (int/string) - either the number of recipients to limit the broadcast sending (should be greater than 2), or string "no limit" (for 'CTR' type).

Optional parameters:

• sender_list_ids (string) - IDs of previously created Sender Lists,
• unsubscriber_list_ids(string) - IDs of previously created Unsubscribe Lists,
• send_date(string) - specific date and time for sending the broadcast (e.g."2020-07-31T14:25:49.614Z"),
• utc_offset - specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0),
• trigger_id - id of the trigger,
• delay - the broadcast will be sent after the trigger event occurs + time of the indicated delay in minutes,
• template_id - id of the message template, if you want to use a specific template for message body,

Continue smart broadcast

Example Request

POST /api/3/Segments HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "broadcast_id": 111
    "message_body": "sample"
    "segment_size": 1
    "send_now": true
    "sender_ids": "1"
    "utc_offset": 180
}

Example Response

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":2.202010018,
  "result":{
        "real_price":0,
        "id":1,
        "broadcast_id":111,
        "utc_offset":180,
        "message_body":"sample",
        "template_id":null,
        "batch_index":null,
        "state":0,
        "recipient_count":1,
        "estimated_price":3.36,
        "send_conditions_id":1,
        "enabled":true,
        "created_at":"2021-06-25 14:02:50",
        "send_time":"2021-06-25 14:02:50",
        "estimated_count":1
  }
}

To continue a smart broadcast:

POST sms.messagewhiz.com/api/3/Segments

Request Parameters

Required:

• broadcast_id (number) - id of the broadcast to be continued
• message_body (string) - message for the segment
• segment_size (number) - count of the recipients whose messages will be sent within the segment
• sender_ids - ids of the senders which will be used for the created segment
• send_now - specifies if the segment should be sent as soon as possible

Optional:

• template_ids - ids of the templates that will be used for the created segment (may be used instead of message_body)
• sender_list_ids - ids of the sender lists which will be used for the created segment (may be used instead of sender_ids)
• trigger_id - id of the trigger that will be used to send the segment (may be used instead of send_now)
• send_date - date when the segment will be send (may be used instead of send_now)
• utc_offset - specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0)
• recipient_cap - count of recipients whose messages will be sent before the broadcast will be paused for further actions (should be specified if a paused CTR Threshold broadcast is being continued)
• first_segment_size - count of the recipients whose messages will be sent within the first segment of the batch (should be specified if a paused CTR Threshold broadcast is being continued)
• next_segment_size - count of the recipients whose messages will be sent within the next segments of the batch (should be specified if a paused CTR Threshold broadcast is being continued)

Send One time password (OTP)

Example Request

POST /api/broadcasts/single?otp=true HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "campaign_id": 1,
 "sender_id": "23",
 "message_body": "verification code: {{verification_code}}",
 "send_date": "2021-03-01T12:41:38.837Z",
 "utc_offset": 120,
 "recipient": "2605876689",
 "verification": true
}

Example Response (200 OK)

{
    "id": 123
}

To send a single sms with an OTP from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/broadcasts/single?otp=true

Request Body

You can pass such parameters in the request body

Required parameters:

• campaign_id (integer) - an ID of a previously created active Campaign,
• message_body - text of the message that the recipient will see ({{verification_code}} token is required).
• sender_id (string) - ID of a previously created Sender,
• recipient (string) - phone number of the Recipient,
• verification (boolean) - indicates if the message should contain an OTP (should be true)

Optional parameters:

• message_template_id (integer) - id of the message template (it should contain {{verification_code}} token, passed instead of message_body)
• sender (string) - name of the Sender (passed instead of sender_id)
• unsubscriber_list_ids (string) - IDs of previously created Unsubscribe Lists
• utc_offset (integer) - specific time zone, in minutes (min -720, max +720, e.g. for UTC+0 the value is 0)
• is_now (bool) - starting condition for the broadcast
• send_date (Date) - specific date and time for sending the broadcast (if is_now: false)
• trigger_id (integer) - id of the trigger (if is_now: false)

Verify OTP

Example Request

POST /api/recipients/{phone_number}/verification HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "verification_code": 2253
}

Example Response (200 OK)

{
    "valid": true
}

To verify an OTP which was sent earlier:

POST https://sms.messagewhiz.com/api/recipients/{phone_number}/verification

Where {phone_number} should be substituted with the phone number of the recipient to whom the OTP has been sent.

Request Body

Only one parameter should be passed in the request body:

• verification_code - the verification code that was sent to the recipient

Get Broadcasts List

Example Request

GET /api/3/Broadcast/List HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json 

Example Response

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.351626371,
    "result": [
        {
            "id": 200,
            "user_id": 123,
            "name": "sample broadcast",
            "type": 1,
            "message_body": "sample message",
            "enabled": 1,
            "trigger_id": null,
            "send_date": "2041-03-07T11:41:55.000Z",
            "state": 2,
            "parent_id": null,
            "real_price": 0,
            "estimated_price": 10.50,
            "create_date": "2019-08-05T13:20:04.000Z",
            "estimated_count": 8,
            "utc_offset": 0,
            "next_segment_size": null,
            "eb_type": null,
            "company_name": "sample company",
            "timezone": "GMT +0",
            "send_now": false,
            "broadcastConversion": {
                "uniqueClicks": 0,
                "totalClicks": 0,
                "recipientCount": 8,
                "conversion": "0.00",
                "broadcastId": 200
            }
        }
    ]
}

Get Broadcasts from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/Broadcast/List

Query Parameters

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

Parameters possible values

• Limit - numbers in range 1-100
• start - any integers
• orderby - Has two values separated by a space (i.g. create_date DESC).
  First value is the field by which results will be ordered. May be send_date or create_date.
  Second value is the order itself. May be ASC or DESC which stands for ascending and descending, respectively.
• filter - Filter has a specific format:
  ?filter={parameter_name}={parameter_value},{parameter_name}...

Available parameters are:

• name - pattern for the broadcast name (the actual name will contain the given string)
• type - type of the broadcast
  • 0 - previous approach singe
  • 1 - previous approach basic broadcast
  • 2 - previous approach smart broadcast
  • 3 - previous approach child broadcast (part of a smart)
  • 10 - single broadcast
  • 11 - basic broadcast
  • 12 - smart broadcast
• parent_id - parent_id of the broadcast (type is automatically set to 3)
• start_date - start of the date range by which to 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=2,type=12,filterBy=create_date,start_date=06/01/2021 12:00 AM
Will find all the smart broadcasts (both approaches) that was created later than 06/01/2021 12:00 AM which name contains sample substring

Single request broadcasts

Example Request

POST /api/3/Broadcast/combinedsubmit HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "message_body": "hello {{first_name}} {{last_name}} here is {{custom2}} click on link {{shorten_url}}!!",
    "sender": "My sender",
    "recipients": [
        {
            "phone_number": 380100001010,
            “first_name": "John",
            "last_name": "Doe",
            "custom2": "MyCustomToken",
            "url": "https://mylink1.com"
        },
        {
            "phone_number": 380100001011,
            "first_name": "Bob",
            "url": "https://mylink2.com"
        }
    ]
}

Example Response

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.351626371,
    "result": [
        {
            "broadcastID":333,
            "segmentID":495
        }
    ]
}

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

Request parameters

Required

• recipients - json file with all needed data (phone number, first name, last name, URL ect. per each recipient)
• sender or sender_id - an ID of previously created sender or a value.
• message_body (string) - text of the message that the recipient will see; can contain text, links, and tokens.

Optional

• name (string) - The name of broadcast is an optional parameter. If it is defined in the request, this value will be used as the name. If it is not provided, the broadcast ID will be used as a name
• send_date (Date) - it can be added to request and the broadcast will be scheduled for the defined date, if not - the broadcast will be sent immediately

Unsubscribe Lists

Unsubscribe lists - lists of numbers that will be excluded from recipient lists and will not receive messages from you. An unsubscribe list consists of the numbers that opted out of your broadcasts as well as numbers you added to the list yourself.

Create a Unsubscribe List (import a file)

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/UnsubscribeList?truncate=true' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}' \
--form 'name=FirstRecipientList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.032846168,
    "result": {
        "enabled": true,
        "id": 123,
        "name": "FirstRecipientList",
        "company_id": 1,
        "unsubscribers_amount": 10,
        "user_id": 1
    }
}

Create an Unsubscribe List by importing file of contacts:

POST https://sms.messagewhiz.com/api/3/UnsubscribeList?truncate=true

Request Body

In the request body, specify the Unsubscribe List details:

• name - name of the Unsubscribe List.

• mapping - the markers to specify the type of stored data in the columns. Possible markers:

  • phone_number - 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 - an absolute path to the file on your device

(e.g /Users/userName/dir/unsubscribers.csv).

Query Parameters

first_name, last_name - max length is 50 symbols, email, url - 255, other - 5000.

if truncate===false and there are fields in the list that exceed the limits, an error while loading occurs.

To check if your file fits, you can preview it.

Create an Unsubscribe List (manually)

Example Request

POST /api/3/unsubscribeList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name":"FirstUnsubscribeList",
    "numbers": [380502222233]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.025868544,
    "result": {
        "enabled": true,
        "id": 21534,
        "name": "FirstUnsubscribeList",
        "company_id": 3182,
        "unsubscribers_amount": 1,
        "user_id": 3191
    }
}

Create an Unsubscribe List from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/unsubscribeList

Request Body

In the request body specify the following:

• name(string) - Unsubscribe List name
• numbers(array) - an array of phone numbers that the Unsubscribe List will consist of

Preview an Unsubscribe List

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/unsubscribeList/preview/4' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' 

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008022008,
    "result": {
        "data": [
            [
                "phone_number"
            ],
            [
                "6593333311"
            ],
            [
                "6593333322"
            ],
            [
                "6593333333"
            ],
            [
                "6593333344"
            ]
        ],
        "isAllNum": [
            true,
            true,
            true,
            true
        ],
        "isExceedLength50": [
            false,
            false,
            false,
            false
        ],
        "isExceedLength255": [
            false,
            false,
            false,
            false
        ],
        "isExceedLength5000": [
            false,
            false,
            false,
            false
        ]
    }
}

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

POST https://sms.messagewhiz.com/api/3/unsubscribeList/preview

Request Body

In the request body, you should specify:

• doc - an absolute path to the file on your device
  

Add Numbers to Unsubscribe List

Example Request

POST /api/3/UnsubscribeList/21534/members HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "numbers":["380502222233", "380643333322"]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.031270908,
    "result": {
        "inserted": 2,
        "alreadyExists": 0,
        "notValid": 0
    }
}

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

POST https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/members

Request Body

In the request body specify:

• numbers(array) - an array of phone numbers that will be added to the Unsubscribe List

Get Unsubscribe Lists

Request Example

GET /api/3/unsubscribeList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.028108664,
    "result": [
        {
            "id": 21534,
            "name": "FirstUnsubscribeList",
            "enabled": 1,
            "unsubscribers_amount": 3
        }
    ]
}

Get Unsubscribe Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/unsubscribeList

Query Parameters

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

For example, to get only an Unsubscribe List with a specific name(e.g FirstUnsubscribeList), use the following query:

https://sms.messagewhiz.com/api/3/RecipientList?filter=name=FirstUnsubscribeList

Get Numbers from Unsubscribe List

Request Example

GET /api/3/unsubscribeList/21534/members  HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.018904092,
    "result": [
        {
            "phone_number": "380643333322"
        },
        {
            "phone_number": "380502327265"
        },
        {
            "phone_number": "380502222233"
        }
    ]
}

Get phone numbers from the specific Unsubscribe List using its ID:

GET https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/members

Download an Unsubscribe List

Request Example

GET /api/3/unsubscribeList/21534/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

"phone_number"
"380502327265"
"380502222233"
"380643333322"

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

GET https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/download

Modify an Unsubscribe List (import a file)

PUT Request Example

curl --location --request PUT 'https://sms.messagewhiz.com/api/3/UnsubscribeList/21534' \
--header 'apikey: <apikey>' \
--form 'mapping={"0":"phone_number"}' \
--form 'doc=@/home/user/Downloads/UnsubscribeList.csv' 

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.040112328,
    "result": {
        "enabled": true,
        "id": 21534,
        "name": "FirstUnsubscribeList",
        "company_id": 3182,
        "unsubscribers_amount": 4,
        "user_id": 3191
    }
}

PATCH Request Example

PATCH /api/3/UnsubscribeList/21534 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": false
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.022112432,
    "result": {
        "id": 21534,
        "enabled": false
    }
}

Replace the entire existing Unsubscribe List with the new imported one:

PUT https://sms.messagewhiz.com/api/3/UnsubscribeList/{id}

Request Body

In the request body specify the new values for this list:

• mapping - the markers to specify the type of stored data above each column.

(e.g {"0":"phone_number"}).

The mapping structure should correspond to the structure presented in the new uploaded file.

• doc - an absolute path to the file on your device.

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

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

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

Disable an Unsubscribe List

Request Example

DELETE /api/3/UnsubscribeList/21567 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.01279094,
    "result": true
}

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

DELETE https://sms.messagewhiz.com/api/3/unsubscribeList/{id}

Links

MessageWhiz provides you with the possibility to include Links in your message broadcasts.
You are able to create and manage Links beforehand, and then just insert them in a message as a Link token({{link:linkId}}).

Create a Link

Example Request

POST /api/3/link HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
  "name":"Link1",
  "url": "https://foot1.com"
  "platform_based_links": {
      "bot_redirect":"https://foot32.com/desktop"
      "preview_url":"https://foot12.com"
  }
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.01954006,
    "result": {
        "id": 165655,
        "name": "Link1",
        "url": "https://foot1.com",
        "enabled": true,
        "type":0,
        "platform_based_links": {
          "bot_redirect":"https://foot32.com/desktop",
          "preview_url":"https://foot12.com"
        }
    }
}

Create a Link from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/link

Request Body

In the request body specify details for the Link that will be created.

Required parameters:

• name(string) - Link name,
• url - Link url itself, in the URI format

Optional parameters:

• platform_based_links - object that has two properties:
  • "bot_redirect" - the recipients who click the link from the PC, will be redirected to this link
  • "preview_url" - will be used to show the preview of your main link

Get Links

Request Example

GET /api/3/link? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.006230324,
    "result": [
        {
            "enabled": true,
            "id": 165655,
            "name": "Link1",
            "url": "https://foot1.com"
        },
        {
            "enabled": true,
            "id": 146746,
            "name": "test",
            "url": "https://sms.messagewhiz.com/app/workspace/links"
        }
    ]
}

Get Links from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/link

Query Parameters

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

For example, to get only a Link with specific URL (e.g https://foot1.com), use the following query:

https://sms.messagewhiz.com/api/3/link?filter=url=https://foot1.com,

or to get a Link by name:

https://sms.messagewhiz.com/api/3/link?filter=name=Link1

Modify a Link

PUT Request Example

PUT /api/3/link/165655 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
  "name": "FirstLink",
  "url": "https://foot1.com",
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.011805652,
    "result": {
        "id": 165655,
        "name": "FirstLink",
        "url": "https://foot1.com",
        "enabled": true
    }
}

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

PUT https://sms.messagewhiz.com/api/3/link/{id}

Request Body

In the request body specify the key and value you want to modify, for example:

{ "name": "FirstLink" }

The same parameters as for the link creation can be used.

Disable a Link

Request Example

DELETE /api/3/link/165655 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.016383932,
    "result": true
}

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

DELETE https://sms.messagewhiz.com/api/3/link/{id}

Monitor link conversion

Example Request

POST /api/3/details/linkConversion HTTP/1.1
Host: sms.messagewhiz.com
apiley: <apikey>
Content-Type: application/json

{
    "url":"mmdsmart.com"
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.12326038,
    "result": {
        "conversion": 100,
        "totalRecipients": 1,
        "clicks": 1
    }
}

To receive conversion data from a certain link:

POST https://sms.messagewhiz.com/api/3/details/linkConversion

Request Body

Only one parameter should be included within the request body:

• url - the link for which you want to monitor conversion

Response Explanation

In the response you can receive 3 main parameters:

• Conversion - level of CTR
• Total Recipients - amount of recipients to which such link was send
• Clicks - amount of unique clicks on the link

Link Lists

MessageWhiz provides you with the possibility to group multiple links into one list. With the help of the Link List token, links from the list will be evenly distributed between recipients of the broadcast. Just insert Link List in a message as a token({{link_list:linkListId}}).

Create a Link List

Example Request

POST /api/3/LinkList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name":"FirstLinkList", 
    "linkIds":["311"]}  

}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.017949384,
    "result": {
        "id": 6940,
        "name": "FirstLinkList",
        "enabled": true,
        "linkListLength": 1,
        "warning":""
    }
}

Create an empty Link List from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/LinkList

Request Body

In the request body specify the name(string) of the Link List that will be created. Either linkIds - an array of IDs of the previously created Links that the list will contain, or links - an array of objects with url and name properties

Example Request

POST /api/3/LinkList/6940/links HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "ids":["146746", "13298"]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.04211898,
    "result": [
        146746
    ]
}

To add existing Links to the Link List, include Link List ID in the query:

POST https://sms.messagewhiz.com/api/3/LinkList/{id}/links

Request Body

In the request body specify the "ids(array)" an array of IDs of the previously created Links that the list will contain. Or specify one link "id(int)"".

Create a Link List (import a file)

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/LinkList' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/linkList.csv' \
--form 'mapping={"0":"name", "1":"url"}' \
--form 'name=FirstLinkList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.105039176,
    "result": {
        "id": 7077,
        "name": "FirstLinkList",
        "enabled": true
    }
}

Create a Link List by importing the file:

POST https://sms.messagewhiz.com/api/3/LinkList

Request Body

In the request body, specify the Link List details:

• name - name of the Link List.

• mapping - the markers to specify the type of stored data in the columns:

  • 0: may have property ("name" or "url"),
  • 1: may have property ("name" or "url"),

The mapping structure should correspond to the structure presented in the uploaded file.

• doc - an absolute path to the file on your device

(e.g /Users/userName/dir/linkList.csv).

Add New Links to a Link List (Bulk)

Example Request

POST /api/3/LinkList/6940/links/bulk HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{"links":

    [{"name": "some3 name", "url": "https://43.url.com"}, {"name": "some3 name 2", "url": "https://24422.url.com"}]

}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.064860264,
    "result": {
        "enabled": true,
        "id": 6940,
        "name": "FirstLinkList",
        "user_id": 3191,
        "company_id": 3182
    }
}

To add multiple new Links to the Link List, you should include Link List ID in the query:

POST https://sms.messagewhiz.com/api/3/LinkList/{id}/links/bulk

Request Body

In the request body specify:

• links(array) - an array of Link objects. Link object should consist of the two required attributes -"name" and "url".

Get Link Lists

Request Example

GET /api/3/LinkList? HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.056359856,
    "result": [
        {
            "id": 6943,
            "name": "LinksList",
            "enabled": 1,
            "conversionCount": 0
        }
    ]
}

Get Link Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/LinkList

Query Parameters

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

Get Links from the List

Request Example

GET  /api/3/LinkList/6941/links HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.010940972,
    "result": [
        {
            "id": 6941,
            "links": [
                {
                    "linkId": 146746,
                    "url": "https://google.com"
                }, 
                {
                    "linkId": 146747,
                    "url": "https://youtube.com"
                }
            ]
        }
    ]
}