API docs by Redocly

MessageWhiz API (4.0.0)

Download OpenAPI specification:

URL: https://sms.messagewhiz.com

General description

Using the MessageWhiz API, you can send individual SMS messages or larger scale messaging broadcasts.

This document will guide you through the core endpoints and functionality of the MessageWhiz 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 integration API keys to allow access to the API. You can generate them for each Team in your organization and distribute these keys to your team members. If you don’t need APIs for specific teams, you can just generate for the default team.

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 actual integration API key.

Generic Replaceable

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

SMS API

Send SMS

Send SMS

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
string or number

This parameter allows you to set a specific Sender name to be used on a single message sent to the end user.

required
string or object

The list of recipients who will get the message. Could contain the list of metadata which will be used in the text.

text
required
string non-empty

The text of the SMS message.

client_ref
string

Optional context value that will be sent back with any response / update related to this request.

callback
string

Optional callback URL that will be called once the status of the delivery changes

api_key
string

API key (alternative to apikey in header)

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

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

Callback payload samples

Callback
Content type
application/json
{ }

Get SMS status by ID

Get SMS status by ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

ID of the SMS which should be specified to receive details about sent sms

Responses

Request samples 

GET /sms/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response samples

Content type
application/json
{
  • "message_id": "string",
  • "from": "string",
  • "to": "string",
  • "text": "string",
  • "status": "string",
  • "client_ref": "string",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "delivered_at": "2019-08-24T14:15:22Z",
  • "pdu_count": 0
}

Authentication API

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 a 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:

Send OTP

Send OTP

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

to
required
string

The end user's phone number to which you want to send a message, as a string of digits without spaces or special characters, beginning with the country dialing code.

use_case
string

Use case of the OTP (for template choosing). AUTH is used by default

language
string

Language of the OTP message template. English (en) is the default language. Russian (ru) is also available

channel
string
Enum: "sms" "voice"

Channel that is set for sending OTP.
Please note: you can use “voice” only in the case when the code is not generated on the Message Whiz side.

verify_code
integer [ 1 .. 999999999 ]

The verification code from the client’s side used for the code challenge. Could be specified from the client’s side or generated by Message Whiz.
Please note: if the “verify_code” is not specified, it will be generated on the Message Whiz side.

client_ref
string

Optional context value that will be sent 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

code_length
integer [ 3 .. 10 ]

The length of the OTP code. This is an optional parameter with a default value of 6.
Please note: the “code_length” parameter could be set only if the code is generated on the Message Whiz side.

lifetime
integer [ 1 .. 1440 ]

The lifetime of the OTP code in minutes. This is an optional parameter with a default value of 1440.
Please note: the “lifetime” parameter could be set only if the code is generated on the Message Whiz side.

verification_attempts
integer [ 1 .. 100 ]

The number of failed attempts allowed before the OTP code expires. This is an optional parameter with a default value of 100.
Please note: the “verification_attempts” parameter could be set only if the code is generated on the Message Whiz side.

api_key
string

API key (alternative to apikey in header)

Responses

Callbacks

Request samples

Content type
application/json
{
  • "from": "MessageWhiz",
  • "to": "1234567890",
  • "use_case": "AUTH",
  • "language": "en",
  • "verify_code": "123456",
  • "client_ref": "123456",
  • "callback": "https://example.com/callback"
}

Response samples

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

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

Get OTP status by ID

Get OTP status by ID

Authorizations:
ApiKeyAuth
path Parameters
message_id
required
string

Message ID of the OTP message

Responses

Request samples 

GET /otp/status/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

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 OTP Code

Verify OTP Code

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

The message ID of the OTP message

verify_code
required
string

The OTP code that was entered by the user

Responses

Request samples

Content type
application/json
{
  • "message_id": "123-123-123-123",
  • "verify_code": "123456"
}

Response samples

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

SMS Broadcast API

Send up to 100 000 SMS messages.

Send sms broadcast messages

Send sms broadcast messages

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
string or number

This parameter allows you to set a specific Sender name to be used for the end user.

required
Array of strings or objects

The list of recipients who will get the message. Could contain the list of metadata which will be used in the text.

text
required
string

Message to send. As placeholders for the recipient's metadata, you can use

{{phone}},

{{email}},

{{URL}},

{{first_name}},

{{last_name}},

{{custom}},

{{custom1}},

{{custom2}},

{{custom3}},

{{custom4}}.

Responses

Request samples

Content type
application/json
{
  • "from": "MySender",
  • "to": [
    ],
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "broadcast_id": "jEr5Hv_eFjnYuDa6"
}

Get status of SMS broadcasts

Get status of SMS broadcasts messages

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

ID of the broadcast

Responses

Request samples 

GET /sms/broadcast/{id} HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response samples

Content type
application/json
{
  • "broadcast_id": "string",
  • "broadcast_status": "string",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "text": "string",
  • "sent_count": 0,
  • "delivered_count": 0,
  • "undelivered_count": 0,
  • "expired_count": 0,
  • "failed_count": 0,
  • "click_count": 0,
  • "cost": 0
}

Detailed Delivery Report

Allows you to get the detailed delivery report of sent broadcast

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

ID of the broadcast

query Parameters
start
integer

start index

limit
integer

limit

Responses

Request samples 

GET /sms/broadcast/{id}/messages?start=0&limit=100 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response samples

Content type
application/json
[
  • {
    }
]

2way messaging API

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 be sent. 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. Start with the country code followed by the recipient number (for example, 447700900000) without a “+” sign or “00” before the country code.

from
required
string <uuid>

Channel ID

channel
required
string
Value: "sms"

The channel on which the message will be sent. 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"
}

2way webhooks API

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.

channelID
required
string

The Channel 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 API

Create customer

Create customer. If the customer creation 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 customer 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 the result are sorted. Default - created

order
string
Enum: "ascending" "descending"

Direction in which the entities will be sorted - 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
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 deletion 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
{}