Skip to main content

Messenger API Reference

API docs by Redocly

Messenger API (3.1.0)

Download OpenAPI specification:Download

E-mail: [email protected] License: Apache 2.0

Introduction

Groupcall Messenger provides a REST-based API for sending text messages and emails via Messenger including recording of messages in the Messenger history screens and, where applicable, charging specific schools for the messages sent on their behalf.

Authentication

The SendMessage API functions has 2 forms of authentication.

Passing an API key and the Customer ID for the specific organisations (Both provided by Groupcall) – These are issued on a per customer basis to the integrator

Passing an API key and the Customer ID for the Partner (Both provided by Groupcall) – This is issued one set per partner and is used for all API use by the partner.

Testing and Development

Groupcall make available a parallel Messenger environment at https://apitesting.groupcall.com/. This is fully isolated from the Messenger production environment.

When a new partner is integrating with Groupcall Messenger we make available a sandbox account on this testing environment for you to develop against the SendMessage API and use the Messenger History page via the UI to view your successes (and failures!). Once you are happy that your integration is ready we can enable transmission of SMS and Email to complete final API testing.

Common Principles

Recipients

The Messenger API is designed to support delegated messages, which in the context of a school would mean: Include the ID of the Student > Send message to Student’s Parent that is held in the Messenger data store You can modify the behaviour of this functionality with the SendTo property:

SendTo Value Description
0 Send directly to defined recipient
1 Send to Priority contact of defined recipient
2 Send to All contacts of defined recipient

Status Callbacks

Pass a URL to receive status updates on the messages that you send. If no parameters are provided, we will include all options in the GET parameters when we call you back.

Customise your callback by including only documented parameters you need in your constructed URL to receive dynamic updates.

You can use our callback testing site to visualise callbacks before implementing your own endpoint. It does require 2 additional parameters beyond what is normally needed: * id - unique reference for your callback * estab - reference for the customer

https://apitesting.xporter.one/Tryit/Callback

Batching

To reduce the number of times you need to call the API to send lots of messages, it is possible to send messages in batches. Multiple recipients can be included for the same message and have personalised content included by populating the optional DynamicTokens object.

Dynamic Tokens

Dynamic property that is the key for your substitution variable. The property name is your token for substitution and the value is the text to insert. Your token must be surrounded by $ eg $TokenName$.

We recommend a maximum of 100 recipients per message. This may mean that you need to generate multiple messages depending on the size of your recipient list for a given message.

Units vs Messages

A single SMS unit is 160 characters long. A message may be comprised of multiple units. Units are the chargeable item, so a message of 200 characters would be charged as 2 SMS units.

  • Unit Length: 160 Characters
  • Maximum Units per Message: 10 Units

SMS message length and Unicode

Overview SMS messages are constructed in sections, referred to as segments. Message sends are costed and charged per segment. In most geographical locations around the world, a single SMS segment represents a maximum of 160 standard GSM characters. Spaces between words are also counted as characters. When typing your message, be aware that the longer it gets, the more it costs.

Long SMS messages

SMS messages containing more than 160 standard GSM characters are known as long messages. Smartphone handsets can combine or stitch multiple SMS segments into a single message. This is a concatenated message. When segments are stitched together, seven characters are sacrificed per segment to help with concatenation. Therefore, the maximum character count for long messages are:

  • 2 message segments: 153+153=306 standard GSM characters
  • 3 message segments: 153+153+153=459 standard GSM characters
  • 4 message segments: 153+153+153+153=612 standard GSM characters

Standard GSM character set

The standard GSM set contains the most widely used characters in everyday language: all Latin characters (A-Z), digits (0-9), plus a few special characters such as Ö and è. For each standard GSM character typed into a message, a single character space is consumed from the SMS segment.

Extended GSM character set

In addition to standard GSM characters, certain characters from the extended GSM character set, such as € and { symbols, can be used in SMS messages. The 160 segment count remains, however these characters use additional space; x2 spaces per character to be exact.

Unicode (non-standard GSM)

Non-standard GSM characters are referred to as Unicode characters. Unicode provides a set of additional characters, including punctuation marks, mathematical symbols, technical symbols, arrows, and characters making up non-Latin alphabets, such as Thai, Chinese, or Arabic script and Emojis. While Unicode is supported in SMS messaging, be aware that its usage affects your message length. Introducing a single Unicode character in your message content changes the character encoding to Unicode (UCS-2) and immediately reduces the segment character limit from 160 to 70 characters for a single message. When messages are stitched together with Unicode characters included, three characters are sacrificed per segment. Therefore:

  • 2 message segments with Unicode: 67+67=134 characters
  • 3 message segments with Unicode: 67+67+67=201 characters
  • 4 message segments with Unicode: 67+67+67+67=268 characters

    Using Emoji in your SMS messages

    Emoji use is supported in SMS messaging. All Emojis are treated as Unicode characters, reducing message segments to 70 characters. Older 16-bit Emojis count as a single character count and newer 32-bit emojis count as two characters in a message.

SMS Delivery & Numbers

SMS messages can be delivered internationally and as such mobile/cell numbers must be provided to the API with their international country code prepended to the number.

US SMS Delivery

Toll Free Numbers These numbers can only be used to deliver within the United States (Region code 1) To send outside of the United States you will need to specify an alphanumeric sender ID by adding SMSSender as an additional property to the messageData object.

SendMessage_V3 Delivery APIs

APIs for sending messages via different routes

Send SMS

This method allows you to batch up multiple SMS messages to be sent to multiple recipients, and optionally to specify a Callback URL for status updates on a per-message per-recipient basis.

Request Body schema: application/json

Example POST body content for sending a single SMS to a single recipient

UserName
required
string

Your ApplicationID, provided by Groupcall

CustomerId
required
string

Unique Customer Id, provided by Groupcall

Password
required
string

Unique API key per customer, provided by Groupcall

SMSMessage
required
string

Content of SMS Message

CallbackUrl
string

Provide URL endpoint to receive status updates and responses

SendDateTime
string

Optionally send date in UTC if planning to send in future, else leave null

SMSSender
string

Alpha numeric string of length 3 to 11 characters. Required when delivering messages internationally (outside of United States)

required
Array of objects (recipientSMS)

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "MessageSentId": 0,
  • "MessageId": "1261.20221107.02517344439098830760-9616fca7b64f405fa9116059403a868f",
  • "statusMsg": "In Queue",
  • "transmitDateTime": "2022-11-07T21:34:51.3826134Z",
  • "ClientRef": "5E4F539B-E2D1-4178-B31F-244E8E403A9F",
  • "WarningMessages": [
    ]
}

Send Email

This method allows you to batch up multiple Email messages to be sent to multiple recipients, and optionally to specify a Callback URL for status updates on a per-message per-recipient basis.

Request Body schema: application/json

Example POST body content for sending a single SMS to a single recipient

Array of objects
Array
callbackUrl
string

Provide URL endpoint to receive status updates and responses

clientRef
string
customerId
required
string

Your ApplicationID, provided by Groupcall

emailBody
required
string

Email body content

emailReplyToAddress
string

Email reply to address

emailSentFromAddress
string

Email sent from address

emailSentFromName
string

Email sent from name

emailSubject
string

Email subject

password
required
string

Unique API key per customer, provided by Groupcall

required
Array of objects

List of recipients

Array of objects

Optional list of attachments

sendDateTime
string
styleClass
required
string

Style class TODO: Expand description

userName
string
object

Optional list of dynamic tokens that can be referenced in the message body

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "MessageSentId": 0,
  • "MessageId": "1261.20221107.02517344439098830760-9616fca7b64f405fa9116059403a868f",
  • "statusMsg": "In Queue",
  • "transmitDateTime": "2022-11-07T21:34:51.3826134Z",
  • "ClientRef": "5E4F539B-E2D1-4178-B31F-244E8E403A9F",
  • "WarningMessages": [
    ]
}

Send Multi Content

This action supports delivery of message content based on customer configured routing rules on a per contact basis.

In your request, you can include content for:

  • SMS
  • Email
  • Push Notification
  • Xpressions

This API method will examine the customer/recipient routing configuration and determine which content to deliver to each defined recipient, based on the customer's configuration in the Groupcall Messenger platform.

When working with schools, it is recommended to include content for all routes to ensure greatest flexibility based on the customer’s configuration and local data.

When identifying your recipient, prefer to use the IdaasId property. It is the unique person identifier in scope of the school obtained from Xporter. It can also be constructed with a consistent prefix per person type and MISID.

PersonType Prefix
Student PL-
Student Contact PC-
Staff PWT-

When working with other organisations or anonymous recipients, provide content for the message type you intend to send eg SMS only.

Request Body schema: application/json

Send Message

Array of objects
Array
callbackUrl
string

Provide URL endpoint to receive status updates and responses

clientRef
string
customerId
required
string

Your ApplicationID, provided by Groupcall

emailBody
required
string

Email body content

emailReplyToAddress
string

Email reply to address

emailSentFromAddress
string

Email sent from address

emailSentFromName
string

Email sent from name

emailSubject
string

Email subject

password
required
string

Unique API key per customer, provided by Groupcall

required
Array of objects (recipientMulti)

List of recipients

Array of objects

Optional list of attachments, only valid

sendDateTime
string
sendXpression
boolean
smsMessage
string
styleClass
string
userName
string
object

Optional list of dynamic tokens that can be referenced in the message body

NotificationMessage
string

Content for Push Notification

XpressionsBody
string

Xpressions body for sending specific content to Xpression, not default SMS/Email

Responses

Callbacks

Request samples

Content type
application/json
{
  • "PartnerKey": "0caad7cf-ad6f-4580-add2-6d941c86f683",
  • "messageData": [
    ],
  • "styleClass": "TestPartner"
}

Response samples

Content type
application/json
{
  • "MessageSentId": 0,
  • "MessageId": "1261.20221107.02517344439098830760-9616fca7b64f405fa9116059403a868f",
  • "statusMsg": "In Queue",
  • "transmitDateTime": "2022-11-07T21:34:51.3826134Z",
  • "ClientRef": "5E4F539B-E2D1-4178-B31F-244E8E403A9F",
  • "WarningMessages": [
    ]
}

SendMessage_V3 Opt In APIs

Get and set opt in/out values for receipients

(Documentation in Progress) Set or update Opt In status for a recipient / number combination

This method allows you to update or set the Opt In status for a recipient and a given incoming number

Request Body schema: application/json

POST body content to set Opt In / Out status for a recipient

CustomerId
required
string

Unique Customer Id, provided by Groupcall

Password
required
string

Unique API key per customer, provided by Groupcall

ShortCode
required
string

Pass your ApplicationID

RecipientNumber
required
string

Mobile / cell number of the individual

Keyword
required
string

SMS Keyword to apply to this recipient eg STOP

SchoolName
string

Pass your ApplicationID

RecipientName
string

Pass your ApplicationID

Responses

Request samples

Content type
application/json
{
  • "CustomerId": 1362,
  • "Password": "424b8416-5656-4b29-bc4c-e46c9f83eea91d08",
  • "ShortCode": "110002233213",
  • "RecipientNumber": "18973434298",
  • "Keyword": "STOP"
}

Response samples

Content type
application/json
{
  • "ShortCode": "110002233213",
  • "RecipientNumber": "18973434298",
  • "IsOptedIn": 0,
  • "Message": ""
}

(Documentation in Progress) Set or update Opt In status for a collection of recipients / numbers combinations

This method allows you to update or set the Opt In status for a collection of recipients for a given incoming number

Responses

Response samples

Content type
application/json
{
  • "MessageSentId": 0,
  • "MessageId": "1261.20221107.02517344439098830760-9616fca7b64f405fa9116059403a868f",
  • "statusMsg": "In Queue",
  • "transmitDateTime": "2022-11-07T21:34:51.3826134Z",
  • "ClientRef": "5E4F539B-E2D1-4178-B31F-244E8E403A9F",
  • "WarningMessages": [
    ]
}

(Documentation in Progress) Fetch the Opt In status of a recipient / number

This method allows you to fetch the current Opt In status of a recipient for a given incoming number

Responses

Response samples

Content type
application/json
{
  • "MessageSentId": 0,
  • "MessageId": "1261.20221107.02517344439098830760-9616fca7b64f405fa9116059403a868f",
  • "statusMsg": "In Queue",
  • "transmitDateTime": "2022-11-07T21:34:51.3826134Z",
  • "ClientRef": "5E4F539B-E2D1-4178-B31F-244E8E403A9F",
  • "WarningMessages": [
    ]
}

SendMessage_V3 Usage APIs

Retrieve usage data for customer accounts

(Documentation in Progress) Fetch the usage data for a specified customer

This method allows you to fetch the usage data for a specified customer within a date range

Responses

Response samples

Content type
application/json
{
  • "MessageSentId": 0,
  • "MessageId": "1261.20221107.02517344439098830760-9616fca7b64f405fa9116059403a868f",
  • "statusMsg": "In Queue",
  • "transmitDateTime": "2022-11-07T21:34:51.3826134Z",
  • "ClientRef": "5E4F539B-E2D1-4178-B31F-244E8E403A9F",
  • "WarningMessages": [
    ]
}