Messages API

Note: This API is only available to Attentive customers. It isn't available to partners.

Make calls to the Messages API to send both SMS and MMS messages to your subscribers. Before you begin, ensure that you're working with a member from our Customer Success team or an engineer at Attentive to coordinate sending test messages with this API. Note that messages are sent using the shortcode assigned during the onboarding process.

With the Messages API, you can either send a message or send messages in bulk.

Send a message

Make a call to this endpoint to send a message to a subscriber.

URL

POST https://api.attentivemobile.com/v1/text/send

Headers

Header name	Description	Value	Required
Authorization	You must provide an access token. A custom app is required to generate an API token. See Create and manage custom apps for details.	`Bearer <token>`	Required
Content-type	The format of returned data.	`application/json`	Required

Parameters

Parameter	Description	Type	Required	Notes
`to`	Subscriber phone number. `subscriberExternalId` must be null if using this identifier.	string	Required*	*Only required if not using `subscriberExternalId`
`subscriberExternalId`	Subscriber external ID. `to` must be null if using this identifier.	integer <int64>	Required*	*Only required if not using `to`
`subscriptionType`	Type of subscriber who will receive the message. Either MARKETING or TRANSACTIONAL.	string	Required
`body`	The body of the MMS/SMS message. If it contains fully qualified links (such as http://www.google.com), they are shortened if `useShortLinks` is set to `true`. The body must not include curly brace characters (`{` `}`). If it does, the message will not be sent and no error notification is provided.	string	Required
`mediaUrl`	URL of the image that accompanies MMS.	string	Optional
`useShortLinks`	Automatically shorten links provided in the `body`. Requires a non-null `messageName`.	boolean	Required
`messageName`	Name of the message to be created for tracking purposes. Restricted to 20 messages in a 24 hour window per company.	string	Optional
`skipFatigue`	Default: `true` Forces a message send to a fatigued subscriber. Applicable to all subscription types.	boolean	Required

Sample JSON request

curl 'https://api.attentivemobile.com/v1/text/send' \
  -X POST \
  -H 'Authorization: Bearer <TOKEN>' \
  -H "Content-Type: application/json" \
  -d '{"to":<PHONE NUMBER>,"body":<MESSAGE TEXT>, "subscriptionType": "TRANSACTIONAL", "useShortLinks": true, "messageName": <MESSAGE_NAME>, "skipFatigue": true}'

Send messages in bulk

Make a call to this endpoint to send messages in bulk to subscribers. Note that we do not accept batches of more than 1,000 messages at a time.

URL

POST https://api.attentivemobile.com/v1/text/send-bulk

Headers

Header name	Description	Value	Required
Authorization	You must provide an access token. A custom app is required to generate an API token. See Create and manage custom apps for details.	`Bearer <token>`	Required
Content-type	The format of returned data.	`application/json`	Required

Parameters

Parameter	Description	Type	Required	Notes
`to`	Subscriber phone number. `subscriberExternalId` must be null if using this identifier.	string	Required*	*Only required if not using `subscriberExternalId`
`subscriberExternalId`	Subscriber external ID. `to` must be null if using this identifier.	integer <int64>	Required*	*Only required if not using `to`
`subscriptionType`	Type of subscriber who will receive the message. Either MARKETING or TRANSACTIONAL.	string	Required
`body`	The body of the MMS/SMS message. If it contains fully qualified links (such as http://www.google.com), they are shortened if `useShortLinks` is set to `true`.	string	Required
`mediaUrl`	URL of the image that accompanies MMS.	string	Optional
`useShortLinks`	Automatically shorten links provided in the `body`. Requires a non-null `messageName`.	boolean	Required
`messageName`	Name of the message to be created for tracking purposes. Restricted to 20 messages in a 24 hour window per company.	string	Optional
`skipFatigue`	Default: `true` Forces a message send to a fatigued subscriber. Applicable to all subscription types.	boolean	Required

Sample JSON request

curl 'https://api.attentivemobile.com/v1/text/send-bulk' \
  -X POST \
  -H 'Authorization: Bearer <TOKEN>' \
  -H "Content-Type: application/json" \
  -d '[{"to":<PHONE NUMBER>,"body":<MESSAGE TEXT>, "subscriptionType":"TRANSACTIONAL", "useShortLinks": true, "messageName": <MESSAGE_NAME>, "skipFatigue": true}, {"to":<PHONE NUMBER>,"body":<MESSAGE TEXT>, "subscriptionType":"TRANSACTIONAL", "useShortLinks": true, "messageName": <MESSAGE_NAME>, "skipFatigue": true]'

Status codes

The following table lists the returned HTTP status codes.

Code	Description	Notes
200	Accepted	Message request was queued for sending successfully.
400	Bad request	Invalid request body or a subscriber was not found.
401	Unauthorized	API key is incorrect.
403	Access denied	n/a
404	The specified source was not found	n/a
429	The user has sent too many requests in a given amount of time	See API rate limits for details.
500	Attentive server-side error	n/a