Sending Messages

You can only send messages to contacts who have opted-in/subscribed through the Loop Message. You can't send messages to random recipients or contacts who have given you consent to contact them through other services.

Send a single message to a specific contact

POST https://a.loopmessage.com/api/v1/message/send/

You can use a contact ID or a phone number/email address (depending on what the user provided you with when subscribing).

Headers

Name	Type	Description
Authorization*	String	API Key. Required*.
Content-Type*	String	application/json

Request Body

Name	Type	Description
contact*	String	Phone number, Email, or Contact ID.
text*	String	Your message text
subject	String	Optional. Your message subject. A recipient will see this subject as a bold title before the text.
sender	String	Optional. ID of your sender name. Send message from a specific sender name.
attachments	Array	Optional. An array of strings. The string must be a full URL of your image. URL should start with https://. HTTP links (without SSL) are not supported. This must be a publicly accessible file URL: we will not be able to reach any URLs that are hidden or that require authentication. Max length of each URL: 256 characters, max elements in the array: 3.
effect	String	Optional. Add effect to your message. Possible values: slam, loud, gentle, invisibleInk, echo, spotlight, balloons, confetti, love, lasers, fireworks, shootingStar, celebration. You can check the Apple guide about expressive messages.
reply_to_id	String	Optional. The message_id that you got from the webhook. You can check the Apple guide about the reply to feature.
passthrough	String	Optional. A string of metadata you wish to store with the checkout. Will be sent alongside all webhooks associated with the outbound message. Max length: 1000 characters.
channel	String	Optional. You can choose which service to use to deliver the message. By default, the required channel will be determined automatically. Possible values: imessage, sms , rcs, or whatsapp. Your sender name must have an active SMS or RCS feature. SMS does not support subject, effect, or reply_to_id parameters. attachments in SMS - only support pictures (MMS). Use this parameter only in cases when you need to override the delivery channel for a specific request. DON'T use it as a default parameter for all requests.
contact_file	Bool	Optional. Add a vCard (Contact file) as an attachment in your message. Use this parameter only in cases when you need to share a contact file. DON'T use it as a default parameter for all requests.

200: OK Request for send received

{
    "message_id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C",
    "contact": "[phone]",
    "text": "text"
}

Phone number will be converted to the next format [phone], without spaces and brackets. Email will be converted into a lowercase format.

400: Bad Request Request for send failed

402: Payment Required No available request. Need purchase additional requests.

Important

When you receive a successful response with code 200 from send request, it means that the server accepted your request for send and added it to the queue. But this does not mean that the message was delivered to the recipient or will be sent.

To handle message status for this request, need to observe Webhooks or use the API method to check the status by message ID, which you received in the JSON response.

We recommend using webhooks to track statuses, as you will receive a callback as soon as an event is fired.

Supported phone number formats

Recipient phone numbers should be only in international formats with a country code. Otherwise will be impossible to verify a phone number.

Plus prefix + is optional. Spaces, dashes '-', brackets '(123)' - also optional.

Valid phone number format examples:

• 13231234567

• [phone]

• [phone]

• [phone]

• 1 (323)-123-4567

Send a single message to an iMessage group

An example of how group chats look like in iMessage

POST https://a.loopmessage.com/api/v1/message/send/

Headers

Name	Type	Description
Authorization*	String	API Key. Required*
Content-Type*	String	application/json

Request Body

Name	Type	Description
group*	String	iMessage group ID. You can only get this ID from the webhook: message_inbound.
text*	String	Your message text
subject	String	Optional. Your message subject. A recipient will see this subject as a bold title before the text.
sender	String	Optional. ID of your sender name. Send message from a specific sender name.
attachments	Array	Optional. An array of strings. The string must be a full URL of your image. URL should start with https://..., http links (without SSL) are not supported. This must be a publicly accessible URL: we will not be able to reach any URLs that are hidden or that require authentication. Max length of each URL: 256 characters, max elements in the array: 3.
effect	String	Optional. Add effect to your message. Possible values: slam, loud, gentle, invisibleInk, echo, spotlight, balloons, confetti, love, lasers, fireworks, shootingStar, celebration. You can check the Apple guide about expressive messages.
reply_to_id	String	Optional. The message_id that you got from the webhook. You can check the Apple guide about the reply to feature.
passthrough	String	Optional. A string of metadata you wish to store with the checkout. Will be sent alongside all webhooks associated with the outbound message. Max length: 1000 characters.

200: OK Request for send received

{
    "message_id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C",
    "group": {
        "id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C",
        "name": "String",  // Optional field
        "participants": ["[phone]", "[phone]"]
    },
    "text": "text"
}

400: Bad Request Request for send failed

402: Payment Required No available request. Need purchase additional requests.

You can't create an iMessage Group, change its name, or add/remove participants to it via the API. You can only receive and reply to incoming messages/attachments.

Send a voice message

An example of how voice/audio messages look in iMessage

POST https://a.loopmessage.com/api/v1/message/send/

Headers

Name	Type	Description
Authorization*	String	API Key. Required*.
Content-Type*	String	application/json

Request Body

Name	Type	Description
contact*	String	Phone number or Email.
media_url*	String	The string must be a full URL of your audio file. URL should start with https://..., http links (without SSL) are not supported. This must be a publicly accessible URL: we will not be able to reach any URLs that are hidden or that require authentication. Max length of each URL: 256 characters. Audio files of the following formats are supported: mp3, wav, m4a, caf, aac.
sender	String	Optional. Your dedicated sender name. This parameter will be ignored if you send a request to a recipient who is added as a sandbox contact. DON'T use a phone number as a value for this parameter.
passthrough	String	A string of metadata you wish to store in the request. Will be sent alongside all webhooks associated with the outbound message. Max length: 1000 characters.

200: OK Request for send received

{
    "message_id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C",
    "recipient": "[phone]",
    "text": "text"
}

Phone number will be converted to the next format [phone], without spaces and brackets. Email will be converted into a lowercase format.

400: Bad Request Request for send failed

402: Payment Required No available request. Need purchase additional requests.

To send a voice message to an iMessage group, you need to use the group field instead contact.

Send a reaction

An example of how tapback reactions looks like in iMessage

POST https://a.loopmessage.com/api/v1/message/send/

Headers

Name	Type	Description
Authorization*	String	API Key. Required*.
Content-Type*	String	application/json

Request Body

Name	Type	Description
contact*	String	Phone number or Email.
message_id*	String	The message_id that you got from the webhook.
reaction*	String	Possible values: love, like, dislike, laugh, emphasize, question, -love, -like, -dislike, -laugh, -emphasize, -question. Reactions that started with - mean "remove" it from the message. You can check the Apple guide about reactions and tapbacks.

Show typing indicator

POST https://a.loopmessage.com/api/v1/message/show-typing/

Headers

Name	Type	Description
Authorization*	String	API Key. Required*.
Content-Type*	String	application/json

Request Body

Name	Type	Description
message_id*	String	The message_id that you got from the webhook.
typing	Integer	This value means how long in the seconds we will show typing indicator. The max value is 60.
read	Bool	Mark conversation as read

Alternatively, you can use the "contact" and "sender" parameters:

Name	Type	Description
contact*	String	Phone number or Email.
sender*	String	ID of your sender name.
typing	Integer	This value means how long in the seconds we will show typing indicator. The max value is 60.
read	Bool	Mark conversation as read. Default true if presenting typing indicator.

The indicator will be automatically hidden as soon as you send an outbound message

Typing indicator limitations

This feature has important limitations. If there is no two-way conversation for more than 5 minutes, then any attempts to show the animation will fail. You should use this feature in active conversations only. In the video below, you can see examples with these limitations.

An example of testing typing indicator between two contacts

Send "Read" status

To let your contacts know that you've accepted a message, you can mark a conversation as read. Todo it, just add "read" to your JSON Body. Example:

{ 
  "typing": 5, // It's optional to show typing indicator here
  "read": true 
}

Failed responses

Please note that in most cases, handling failed responses can be far more important than handling successful ones. If something goes wrong, it may help to quickly take further action.

If your request has a failed status, you will receive a JSON response with the following content:

{
    "success": false,
    "code": 100,
    "message": "string"
}

It is important to implement handling the "code" field. It helps to understand how to manage your further actions according to the error code.

The message field is optional and briefly describes the reason for the error. Please do not pass this to the destination users/recipients. Use the "code" field to map errors and show localized error text to them.

Response example

200: OK Request for send received

{
    "message_id": "2BC4FD6A-CE49-439F-81DF-E895C09CA49C",
    "success": true,
    "recipient": "[phone]",
    "text": "text"
}

Phone number will be converted to the next format [phone], without spaces and brackets. Email will be converted into a lowercase format.

400: Bad Request Request for send failed

402: Payment Required No available request. Need purchase additional requests.

Limits

Messages

• If you need to send messages to a few contacts who haven't recently sent you any inbound messages, you must keep a minimal interval of 2 minutes between each such message. Otherwise, your request may be rejected.

• Max text length in each message must be less than 10000 characters. Otherwise, all extra characters will be truncated. If you have larger requirements, we recommend breaking the message up into several smaller messages.

  You can use characters from any language, emojis, and \n for new lines. HTML tags aren't supported.

Attachments

• When you send an attachment file for the first time, it takes a while for it to download into the cache before it's sent to the recipient. If your attachments are large (more than a couple of megabytes), it will take a while for them to be delivered to your contact. If you update your file but it still has the same URL, the cached version still be used. To avoid a cached version, you need to change the file URL (for example, by renaming the file name).

Best Practices

Handling failed cases

It's recommended to implement handling of the next failed/error cases:

• If the response code for sending a message is not equal 200. In most cases, it means that something is wrong with your parameters.

• You receive a webhook with the type message_failed or message status is failed. This means that the message can't be delivered to this recipient. Check the error_code JSON field to better understand your case.

• You receive a webhook with the type message_sent, but the success JSON field contains the false value. That means a message was successfully sent, but it was unsuccessfully delivered on the recipient side. Examples: your recipient blocked you or uses filters from unknown senders. This case is equal to "Not delivered" status in the Messages app.

• You receive a webhook with the type message_timeout or message status is timeout. This happens if you passed the timeout parameter in the request to send a single message. In this case, this means that we failed to deliver a message within the specified time, and it was assigned the timeout status.