Sending Messages
Send single message
Request to send a text in iMessage to an individual recipient
POST https://server.loopmessage.com/api/v1/message/send/
Use this endpoint to submit a message request to the sending queue.
Headers
Authorization*
String
Authorization Key
Loop-Secret-Key*
String
API Secret Key
Content-Type*
String
application/json
Request Body
recipient*
String
Phone number or Email.
text*
String
Your message text
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.
timeout
Integer
Value in seconds. If sending takes longer than the specified seconds, the request will be canceled. The value can't be less than 5 sec.
sender_name*
String
Your dedicated sender name. This parameter will be ignored if you send a request to a recipient who is added as a sandbox contact. If you've connected a phone number, you'll need to keep passing your original sender name. 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.
status_callback
String
The URL where you want to receive the status updates of the message. Check the Webhooks section for details. Max length: 256 characters.
status_callback_header
String
The custom Authorization header will be contained in the callback. Max length: 256 characters.
reply_to_id
String
The message_id that you got from the webhook.
You can check the Apple guide about the reply to feature.
subject
String
Your message subject. A recipient will see this subject as a bold title before the text.
effect
String
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.
service
Optional. You can choose which service to use to deliver the message.
Possible values: imessage or sms. The default value is imessage. Your sender name must have an active SMS feature.
SMS does not support subject, effect, or reply_to_id parameters. attachments in SMS - only support pictures (MMS).
Phone number will be converted to the next format +13231112233, without spaces and brackets. Email will be converted into a lowercase format.
Important
When you receive success 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 messages status for this request, need to observe Webhooks or use API method to check the status by message ID which you received in JSON response.
We recommend using webhooks to track statuses, as you will receive a callback as soon as an event occurs.
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
+13231111111
+1 (323) 1111111
+1 323 123 4567
1 (323)-123-4567
Text limits
Max text length 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.
Send single message to iMessage group
Request to send a message to an iMessage group
POST https://server.loopmessage.com/api/v1/message/send/
Headers
Authorization*
String
Authorization Key
Loop-Secret-Key*
String
API Secret Key
Content-Type*
String
application/json
Request Body
group*
String
iMessage group ID. You can only get this ID from the webhook group_created or message_inbound.
text*
String
Your message text
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.
timeout
Integer
Value in seconds. If sending takes longer than the specified seconds, the request will be canceled. The value can't be less than 5 sec.
sender_name*
String
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 with the checkout. Will be sent alongside all webhooks associated with the outbound message. Max length: 1000 characters.
status_callback
String
The URL where you want to receive the status updates of the message. Check the Webhooks section for details. Max length: 256 characters.
status_callback_header
String
The custom Authorization header will be contained in the callback. Max length: 256 characters.
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 audio message
Request to send an audio file as voice message
POST https://server.loopmessage.com/api/v1/message/send/
Headers
Authorization*
String
Authorization Key
Loop-Secret-Key*
String
API Secret Key
Content-Type*
String
application/json
Request Body
recipient*
String
Phone number or Email.
text*
String
Your message text
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_name*
String
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.
status_callback
String
The URL where you want to receive the status updates of the message. Check the Webhooks section for details. Max length: 256 characters.
status_callback_header
String
The custom Authorization header will be contained in the callback. Max length: 256 characters.
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.
audio_message*
Bool
Specifying that the message will be delivered as voice/audio.
Phone number will be converted to the next format +13231112233, without spaces and brackets. Email will be converted into a lowercase format.
This feature is under the beta. If you find any issues with this feature, please contact support.
To send audio message to an iMessage group you will need to use group field instead recipient.
Send a reaction
Request to send reaction to iMessage
POST https://server.loopmessage.com/api/v1/message/send/
Headers
Authorization*
String
Authorization Key
Loop-Secret-Key*
String
API Secret Key
Content-Type*
String
application/json
Request Body
recipient*
String
Phone number or Email.
text*
String
Your message text
message_id*
String
The message_id that you got from the webhook.
sender_name*
String
Your dedicated sender name. This parameter will be ignored if you send a request to a recipient who is added as a sandbox contact.
status_callback
String
The URL where you want to receive the status updates of the message. Check the Webhooks section for details. Max length: 256 characters.
status_callback_header
String
The custom Authorization header will be contained in the callback. Max length: 256 characters.
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.
reaction*
String
Possible values:
love, like, dislike, laugh, exclaim, question, -love, -like, -dislike, -laugh, -exclaim, -question. Reactions that started with - mean "remove" it from the message.
You can check the Apple guide about reactions and tapbacks.
Phone number will be converted to the next format +13231112233, without spaces and brackets. Email will be converted into a lowercase format.
To send reactions to an iMessage group you will need to use group field instead recipient.
Failed requests
If your request has a failed status, you will receive a JSON response with the following content:
The "message" field is optional and is intended to briefly inform the developer about the cause of the error. Please do not pass this to the destination users who initiated the message request. Use the "code" field to map errors and show localized error text to them.
Error codes
Bad request
Missing credentials in request
One or more required parameters for the request are missing
Authorization key is invalid or does not exist
Secret key is invalid or does not exist
No "text" parameter in request
No "recipient" parameter in request
Invalid recipient
Invalid recipient email
Invalid recipient phone number
A phone number is not mobile
Sender name not specified in request parameters
Invalid sender name
An internal error occurred while trying to use the specified sender name.
Sender name is not activated or unpaid
This recipient blocked any type of messages
Unable to send this type of message without dedicated sender name
You send messages too frequently to recipients you haven't contacted for a long time. You need to keep intervals between such messages to prevent suspension of your sender name by Apple.
No available requests/credits on your balance
Your account is suspended
Your account is blocked
Your account is suspended due to debt
No active purchased sender name to send message
Your sender name has been suspended by Apple
Requires a dedicated sender name or need to add this recipient as sandbox contact
Unable to send outbound messages until this recipient initiates a conversation with your sender.
This API request is deprecated and not supported
Invalid effect parameter
Invalid message_id for reply
Invalid or non-existent message_id
Invalid reaction parameter
reaction or message_id is invalid or does not exist
Unable to use effect and reaction parameters in the same request.
Need to set up a vCard file for this sender name in the dashboard
No media file URL - media_url
Unable to send SMS if the recipient is an email address
Unable to send SMS if the recipient is group
Unable to send SMS with marketing content
Unable to send audio messages through SMS
This list only describes the error codes you may receive when using endpoints from this page. Webhooks have separate error codes, which you can find in the Webhooks Error Codes section.
Best Practices
Handling failed cases
There may be cases when impossible to deliver your text via iMessage, this can happen if, for example, your recipient is an Android user. We recommend that you handle the following cases to determine when failed to send a text via iMessage:
If the response code for sending message is not equal
200. In most cases, this means that the send request is incorrect.\You receive a webhook with the type
message_failedor message status isfailed. This means that the message can't be delivered to this recipient. Check theerror_codeJSON field to better understand your case.\You receive a webhook with the type
message_sent, but thesuccessJSON field contains thefalsevalue. 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 equal to "Not delivered" status in the Messages app.\You receive a webhook with the type
message_timeoutor message status istimeout. This happens if you passed thetimeoutparameter 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.
Typing indicator and read status
You can use these features to make chatting more interactive while a recipient waiting for a response.
Show typing indicator\
You can show a typing indicator to let your contact know that you are processing their message. Check the "Show typing indicator" section in the Webooks/Callbacks for details. Please note that there is no separate request to show a read status or typing indicator. You can only implement this via webhooks.
Send read status\
You can send a read status to a chat to let your contacts know that you have accepted the message and are processing it. Check the "Send read status" section in the Webooks/Callbacks for details. Please note that there is no separate request to show a read status or typing indicator. You can only implement this via webhooks.
Performance
The queue for sending goes according to the FIFO principle. This means that every time you send a request, you add a new operation to the queue. All these operations in the queue work synchronously. Duration for each operation could take up to 1 seconds.
Each dedicated sender name has its own send queue. If you need to reach asynchronous messaging, you need to use multiple dedicated sender names equivalent to the number of queues required.
Attachment's cache
Each sender name has its own cache. When you send an attachment for the first time, it takes some time for it to download into the cache before being sent to the recipient. If your attachments have a large size (more than a couple of megabytes), it will take some time until it is delivered to your contact. To minimize this delay between sending the text and attachments, you can send yourself a test message with an attachment. Thus, your files will be downloaded into the cache and all your subsequent requests will be instantly delivered.
Last updated