SMS Messaging

Send message

Changed on Jul 4, 2022

MessageBird's Programmable SMS API enables you to programmatically send SMS messages from your web application.

First, you need to create a new message object. MessageBird returns the created message object with each request. A maximum of 50 recipients can be entered per request.

post/messages

Request

Base URL: https://rest.messagebird.com/messages
URL: https://rest.messagebird.com/messages/messages
Auth: API key in header Authorization

Headers

Content-Typestring required

Authorizationstring required

Request body

originatorstring required

The sender of the message. This can be a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters.

bodystring required

The body of the SMS message.

recipientsstring[] required

An array of recipients msisdns.

groupIdsstring[]

An array of group id's. If provided recipients can be omitted.

type'sms' | 'binary' | 'flash'

The type of message. Values can be: sms, binary, or flash.

referencestring

A client reference. Is required for a status report callback to be sent.

reportUrlstring

The status report URL to be used on a per-message basis. This value overrides the standard status report url configured on the customer account.

validityinteger

The amount of seconds that the message is valid. If a message is not delivered within this time, the message will be discarded.

gatewayinteger

The SMS route that is used to send the message.

typeDetailsobject

A hashmap with extra information.

datacodingstring

The datacoding used, defaults to plain (GSM 03.38 characters only), or it can be set to unicode (contains non-GSM 03.38 characters) or set to auto and we will set unicode or plain depending on the body content.

mclassinteger

Indicated the message type. 1 is a normal message, 0 is a flash message. (0-3 are valid values).

shortenUrlsboolean

*beta* Shorten all the URLs present in the message body.

scheduledDatetimeinteger

The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP), when you want to schedule a message in the future. Don't set this value when message needs to be send directly.

Example request

{
  "recipients": "+380999999999",
  "originator": "MessageBird",
  "body": "Lorem ipsum dolor sit amet.",
  "type": "binary",
  "reference": "test",
  "reportUrl": "https://example.com/callback",
  "validity": 30,
  "gateway": 11,
  "typeDetails": {
    "udh": "050003340201"
  },
  "datacoding": "unicode",
  "mclass": 1,
  "shortenUrls": true,
  "scheduledDatetime": null
}

Response

SMS successfully created

object required

Changes

Jul 4, 202248bb1cc832d5 Revision changes
- warning
  the optional response header Alt-Svc removed for the status 201
- warning
  the optional response header Alt-Svc removed for the status 401
- warning
  the optional response header Alt-Svc removed for the status 422
- warning
  the optional response header Server removed for the status 201
- warning
  the optional response header Server removed for the status 401
- warning
  the optional response header Server removed for the status 422
- warning
  the optional response header Via removed for the status 201
- warning
  the optional response header Via removed for the status 401
- warning
  the optional response header Via removed for the status 422
- warning
  the optional response header X-CLOUD-TRACE-CONTEXT removed for the status 201
- warning
  the optional response header X-CLOUD-TRACE-CONTEXT removed for the status 401
- warning
  the optional response header X-CLOUD-TRACE-CONTEXT removed for the status 422

Operation history