+1-800-676-5500 +1-800-676-5500

WhatsApp API

Expand your messaging horizons

Introduction

WhatsApp Business API is a communication solution that provides media-rich white-label messaging via one of the world’s most prominent OTT messaging channels. Our clients now have the opportunity to reach WhatsApp’s 2 billion monthly active users through a sophisticated, easy-to-use integration.

SMSGlobal’s WhatsApp Business API provides a robust gateway for our clients to utilize enterprise messaging on WhatsApp. With the opportunity to reach WhatsApp’s notable 2 billion monthly active users, this API allows trusted businesses to connect with customers directly.

Integrate SMSGlobal’s WhatsApp Business API to established backend systems and enable all the possibilities of rich, contextual, business-grade communication on WhatsApp.

REST API Scroll to Top ▲

The REST API allows programmatic access to SMSGlobal features in MXT. To use the REST API, you will need an MXT account and an API key and secret. You can generate these inside your MXT account. The REST API can be accessed at api.smsglobal.com. Use of SSL is supported and strongly encouraged. The REST API takes full advantage of all HTTP headers. Each part of a request and response is meaningful, including the request method (GET/POST, etc.), the individual headers (Location, Content-Type, Accept, etc.), and the response status code (200, 400, 404, etc.). Use of this API assumes a working knowledge of these HTTP components, and general use of RESTful web APIs.

Authentication Scroll to Top ▲

The REST API uses an authentication scheme based on this OAuth 2 specification . All requests to resources (excluding the schema pages) must be accompanied by a correct Authorization header as per this specification. The header looks like this:

 Authorization: MAC id="your API key", ts="1325376000", nonce="random-string", mac="base64-encoded-hash"

Response Codes Scroll to Top ▲

The following response codes apply to all requests. Check each request type in the list below for more response codes specific to that request.

Status CodeMeaningScenario

200

OK

The request was processed successfully

400

Bad Request

Your request contained invalid or missing data

401

Unauthorized

Authentication failed or the Authenticate header was not provided

404

Not Found

The URI does not match any of the recognised resources, or, if you are asking for a specific resource with an ID, that resource does not exist

405

Method Not Allowed

The HTTP request method you are trying to use is not allowed. Make an OPTIONS request to see the allowed methods

406

Not Acceptable

The Accept content type you are asking for is not supported by the REST API

415

Unsupported Media Type

The Content-Type header is not supported by the REST API

Message Object Types Scroll to Top ▲

The types of messages that can be sent include the following:

Template message

JSON object parameters:

NameDescriptionJSON TypeDefaultConstraintsRequired
typeConstant value template.StringN/AN/AYes
template_nameName of the template.StringN/AN/AYes
paramsParameters to inject into the template.String arrayN/AThis parameter can only be used for template messages with only a body of text.No
Text message

JSON object parameters:

NameDescriptionJSON TypeDefaultConstraintsRequired
typeConstant value textStringN/AN/AYes
preview_urlMessage objectBooleanfalsetrue or falseNo
TextThe text message contentStringN/AValid URLYes
Image message

Accepted content types can be found in the table below

JSON object parameters:

NameDescriptionJSON TypeDefaultConstraintsRequired
typeConstant value imageStringN/AN/AYes
urlPublic url of the image file. Should be either HTTP or HTTPS link.StringN/AAccepted Content-Type headerYes
captionOptional caption that will be displayed underneath the image.StringNoneN/ANo
Video message

Accepted content types can be found in the table below

JSON object parameters:

NameDescriptionJSON TypeDefaultConstraintsRequired
typeConstant value videoStringN/AN/AYes
urlPublic url of the video file (mp4). Should be either HTTP or HTTPS link.StringN/AAccepted Content-Type headerYes
captionOptional caption that will be displayed underneath the video.StringNoneN/ANo
Document message

Accepted content types can be found in the table below

JSON object parameters:

NameDescriptionJSON TypeDefaultConstraintsRequired
typeConstant value documentStringN/AN/AYes
urlPublic url of the document file. Should be either HTTP or HTTPS link.StringN/AAccepted Content-Type headerYes
filenameOptional parameter that describes the filename of the document.StringNoneN/ANo
captionOptional caption that will be displayed as the document title.StringNoneN/ANo
Audio message

Accepted content types can be found in the table below

JSON object parameters:

NameDescriptionJSON TypeDefaultConstraintsRequired
typeConstant value audioStringN/AN/AYes
urlPublic url of the audio file. Should be either HTTP or HTTPS link.StringN/AAccepted Content-Type headerYes
Location message

JSON object parameters:

NameDescriptionJSON TypeDefaultConstraintsRequired
typeConstant value locationStringN/AN/AYes
latThe latitude position as a float number.NumberN/A[-90, 90]Yes
lngThe longitude position as a float number.NumberN/A[-180, 180]Yes
nameThe name for the location. Will be displayed in the message.StringN/AN/ANo
addressThe address for the location. Will be displayed in the message.StringN/AN/ANo
Accepted media types
Message TypeSupported content typesPost-processing size limit
documentAny content type listed for other message types,





text/plain, text/csv, application/pdf, application/msword, application/x-tar, application/rtf.0, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation,
application/vnd.openxmlformats-officedocument.wordprocessingml.document,
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,
application/vnd.oasis.opendocument.presentation,
application/vnd.oasis.opendocument.spreadsheet,
application/vnd.ms-excel, application/vnd.oasis.opendocument.text		100 MB
imageimage/jpeg, image/png5 MB
audioaudio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg, audio/opus16 MB
videovideo/mp4, video/3gpp16 MB
stickerimage/webp100 KB

API Endpoints Scroll to Top ▲

  • whatsapp
    /v2/whatsapp/blacklist
    • POST /v2/whatsapp/blacklist beta since v2

      Documentation

      Block messages from number(s)

      Parameters

      ParameterTypeRequired?FormatDescription
      numbers[]array of stringstrueList of numbers

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/capabilities
    • POST /v2/whatsapp/capabilities beta since v2

      Documentation

      Check capability of number(s) to receive messages

      Parameters

      ParameterTypeRequired?FormatDescription
      numbers[]array of stringstrueList of numbers

      Return

      ParameterTypeVersionsDescription
      capabilities[]array of objects (WhatsappOptIn)>=v2A collection of opt-in objects
      capabilities[][name]string>=v2Name
      capabilities[][number]string>=v2Number
      capabilities[][capable]boolean>=v2Capability
      capabilities[][blacklist]boolean>=v2Notification blacklist

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/incoming
    • GET /v2/whatsapp/incoming beta since v2

      Documentation

      Get list of incoming messages

      Filters

      NameInformation
      offsetRequirement \d+
      Description Pagination offset (default 1, maximum offset + limit = 10,000)
      Default 1
      limitRequirement \d+
      Description Number of items to return (default 20, maximum 1000)
      Default 20
      startDateRequirement
      Description Start date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
      endDateRequirement
      Description End date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
      destinationRequirement \d+
      Description The shared pool or dedicated number which the sms was sent to
      originRequirement \d+
      Description The number where the SMS appears to come from
      searchRequirement
      Description Search string in source, destination and message

      Return

      ParameterTypeVersionsDescription
      messages[]array of objects (WhatsappIncoming)>=v2A collection of message objects
      messages[][id]integer>=v2Message id
      messages[][from]string>=v2From
      messages[][to]string>=v2To
      messages[][message]string>=v2Message
      messages[][createdDate]DateTime>=v2Create date

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/incoming/read
    • POST /v2/whatsapp/incoming/read beta since v2

      Documentation

      Update incoming message(s) to read status

      Parameters

      ParameterTypeRequired?FormatDescription
      ids[]array of stringstrueList of ids

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/incoming/{id}
    • GET /v2/whatsapp/incoming/{id} beta since v2

      Documentation

      Get an incoming message

      Requirements

      NameRequirementTypeDescription
      id

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2Message id
      fromstring>=v2From
      tostring>=v2To
      messagestring>=v2Message
      createdDateDateTime>=v2Created date

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/message
    • GET /v2/whatsapp/message beta since v2

      Documentation

      Get list of outgoing messages

      Filters

      NameInformation
      offsetRequirement \d+
      Description Pagination offset (default 1, maximum offset + limit = 10,000)
      Default 1
      limitRequirement \d+
      Number of items to return (default 20, maximum 1000)
      Default 20
      startDateRequirement
      Description Start date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
      endDateRequirement
      Description End date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
      destinationRequirement \d+
      Description The shared pool or dedicated number which the sms was sent to
      originRequirement \d+
      Description The number where the SMS appears to come from
      searchRequirement
      Description Search string in source, destination and message

      Return

      ParameterTypeVersionsDescription
      messages[]array of objects (WhatsappMessage)>=v2A collection of message objects
      messages[][id]integer>=v2Message id
      messages[][recipient]string>=v2Recipient
      messages[][status]string>=v2Status
      messages[][state]string>=v2State
      messages[][message]string>=v2Message
      messages[][createdDate]DateTime>=v2Created date

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    • POST /v2/whatsapp/message beta since v2

      Documentation

      Send a message

      Parameters

      ParameterTypeRequired?FormatDescription
      to[]array of stringstrueList of destination
      messagestringtrue

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2Message id
      recipientstring>=v2Recipient
      statusstring>=v2Status
      statestring>=v2State
      messagestring>=v2Message
      createdDateDateTime>=v2Created date

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/message/{id}
    • GET /v2/whatsapp/message/{id} beta since v2

      Documentation

      Get an outgoing message

      Requirements

      NameRequirementTypeDescription
      id

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2Message id
      recipientstring>=v2Recipient
      statusstring>=v2Status
      statestring>=v2State
      messagestring>=v2Message
      createdDateDateTime>=v2Created date

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/opt-in
    • GET /v2/whatsapp/opt-in beta since v2

      Documentation

      Show opted in numbers

      Return

      ParameterTypeVersionsDescription
      optIn[]array of objects (WhatsappOptIn)>=v2A collection of opt-in objects
      optIn[][name]string>=v2Name
      optIn[][number]string>=v2Number
      optIn[][capable]boolean>=v2Capability
      optIn[][blacklist]boolean>=v2Notification blacklist

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    • POST /v2/whatsapp/opt-in beta since v2

      Documentation

      Opt in numbers

      Parameters

      ParameterTypeRequired?FormatDescription
      opt-in[]array of objects (WhatsappOptInExtendedType)trueA collection of opt in
      opt-in[][name]stringfalse
      opt-in[][number]stringtrue

      Return

      ParameterTypeVersionsDescription
      optIn[]array of objects (WhatsappOptIn)>=v2A collection of opt-in objects
      optIn[][name]string>=v2Name
      optIn[][number]string>=v2Number
      optIn[][capable]boolean>=v2Capability
      optIn[][blacklist]boolean>=v2Notification blacklist

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/whatsapp/opt-out
    • POST /v2/whatsapp/opt-out beta since v2

      Documentation

      Opt out numbers

      Parameters

      ParameterTypeRequired?FormatDescription
      numbers[]array of stringstrueList of numbers

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
Early Access

WhatsApp Business API

Loading Form