Webhooks/Callbacks

Handle status of message for each request

Through webhooks, you can receive notifications when an event is fired. In most cases, it is a good idea to start processing inbound messages and then process the statuses of outbound messages.

Registering and processing webhooks

For each organization, you can specify separate webhook URLs and headers for events.

Our server will send POST requests to your server, in which the body will be a JSON representation of the notification. Your server should return a 200 status code. Any other status code will be considered a failure by our backend. Our server will retry later (up to 30 times) with an increasing delay. First 10 retries every 30 seconds, the next 10 retries every 3 mins, and the last 10 retries every 15 mins. After 30 retries, we will stop sending notifications.

If your service/app doesn't return a response within 15 seconds, our server will disconnect and reschedule a webhook for retry. It's highly recommended that your apps/services defer processing until return a response with a status code 200.

Webhook Events

Sample Webhook Events

These are some representative samples of webhooks you might receive from LoopMessage. Keep in mind that webhooks can include additional fields to what's shown here.

Inbound

{
    "event": "message_inbound",
    "contact": "[phone]",
    "text": "text",
    "message_type": "text",
    "message_id": "59c55Ce8-41d6-43Cc-9116-8cfb2e696D7b",
    "webhook_id": "ab5Ae733-cCFc-4025-9987-7279b26bE71b",
    "api_version": "1.0"
}

Scheduled

Failed

Delivered

Reaction

Possible JSON fields in webhooks

Field	Type	Description
message_id	String	Unique identifier of your request/message.
webhook_id	String	Unique identifier of the event.
event	String	Check the Event Types section for possible values.
contact	String	The contact to which the event relates. Contact can be a phone number or email address. A phone number will be in the E164 format: [phone], without spaces and brackets. Email will be in lowercase format.
text	String	Text in the message.
subject	String	Optional Field. Message subject.
attachments	Array	Optional Field with an array of strings. This field will only be for the event: message_inbound. Each element of the array is the URL to download the file.
message_type	String	This field will only be for events: message_inbound or message_reaction. Possible values: text, reaction, audio, attachments, sticker, location.
channel	String	How the message was sent/received. Possible values: imessage, sms, rcs.
reaction	String	Indicates if a contact reacted to your message. This field will only be for the event: message_reaction. Possible values: love, like, dislike, laugh, emphasize, question, unknown.
sender	String	Dedicated sender name ID.
thread_id	String	Optional field. If the contact tapped reply-to it will create a conversation thread in the iMessage. This identifier will help you understand to which thread the message is related.
error_code	Integer	Error code that occurred while processing the request. This field will only be for the event: message_failed.
language	Object	The dominant language that is used in the text. Check the language section for details.
group	Object	Data related to the iMessage group. Check the group section for details.
speech	Object	Optional field. Transcription of an inbound audio message. Will be contained in the JSON only if the speech recognition was done successfully. Check the speech section for details.

Event Types

All values will be in lowercase and in snake_case format

Event type	Description
opt-in	Your contact first time sent an inbound message to your sender name.
message_failed	Failed to send or deliver a message. Further events related to your request will no longer be fired.
message_delivered	The message has been delivered.
message_inbound	Contact sent you an inbound message.
message_reaction	Contact put a reaction to your text. For example Like, Love and etc.
inbound_call	Your contact attempted to call via FaceTime.
unknown	An unknown event has occurred

Language

Key	Value
code	ISO 639-1 code. Examples: en, fr, de, ja, zh.
name	Examples: English, French, German, Japanese, Chinese.
script	Optional field. Supported only two values for the Chinese language: -Hans: Simplified Chinese script -Hant: Traditional Chinese script

The dominant language in the text. These values are approximate and may be incorrect if the message is less than 100 characters long or contains text in several languages.

Group

Key	Value
id	Unique ID of iMessage group. You can use this value as the contact/recipient value in the send messages requests.
name	Optional field. Custom name for this group (if named).
participants	An array of strings (participants) in this group. Values in the array can be a phone number (in E164 format) or email (in lowercase format).

Speech

Key	Value
text	Text transcription from audio message
language	Language object. The dominant language that is used in the text. Check the language section for details.
metadata	Optional field. The metadata of speech in the audio message. Check the speech metadata section for details.

These values are approximate and may be incorrect if the voice is too long, unclear, or in several languages.

Speech metadata

Any field in this object can be optional. All values are float type.

Key	Value
speaking_rate	Measures the number of words spoken per minute.
average_pause_duration	Measures average pause between words (in seconds).
speech_start_timestamp	Timestamp of start of speech in audio.
speech_duration	Duration of speech in audio.
jitter	Jitter measures vocal stability and is measured as an absolute difference between consecutive periods, divided by the average period. It is expressed as a percentage.
shimmer	Shimmer measures vocal stability and is measured in decibels.
pitch	Pitch measures the highness and lowness of tone and is measured in logarithm of normalized pitch estimates.
voicing	Voicing measures the probability of whether a frame is voiced or not and is measured as a probability.

Headers

These headers will be included in any webhook POST request.

Key	Value
Content-Type	application/json
User-Agent	LoopCampaign
Connection	close

Best practices

Authorization

You can configure the authorization header used for webhook requests via the dashboard. Your server should verify the validity of the authorization header for every event. This will help you make sure that a webhook was sent from our service.

IP Whitelisting

The webhook IP range is variable so we don't recommend hardcode IP of our server. To authenticate requests you can add an authorization token to the webhook that you can then verify on your server.

Response Duration

Try to return a response immediately so as not to accidentally reach the timeout duration.

If this happens, you can use webhook_id as a unique identifier to avoid processing the same event twice. But even in this case, you need to return a response with the code 200 to stop firing a webhook.

Please note that if you are using ngrok or similar services, the timeout time will be much shorter to prevent abuse by keeping many dummy connections.

Security and encryption

It is highly recommended to use HTTPS URLs for webhooks. If you use HTTP URLs (without SSL), requests to your server will not be encrypted and the contents of your requests/messages may be intercepted. In some cases, webhooks for HTTP URLs (without SSL) may not be delivered.

Future-Proofing

You should be able to handle webhooks that include all important fields to what's shown here, including new event types. We may add new fields or event types in the future without changing the API version. We won't remove fields or events without proper API versioning and deprecation.