Introduction
If your system needs to take action on certain events happening in your Call-Em-All account, then web-hooks is for you. Instead of sitting in the dark or continuously polling the Call-Em-All API, you can have Call-Em-All send notifications to a web-hook that you've built whenever important events happen in your Call-Em-All account. For example, we can send a message to your web-hook when:
- a broadcast is created, starts broadcasting, completes, and more
- an inbound text is received
- someone opts out of receiving your texts or calls
- someone opts into receiving your texts or calls
- a user on your account sends a conversation text
- and more!
Sign Up
Soon, you will be able to use a Call-Em-All API function to subscribe to events you need. For now, please send an email to api@call-em-all.com and we'll enroll you. Include the following in your email:
- The URL that Call-Em-All will hit when an event triggers.
- Web-hooks will be made using basic authentication. We need the username and password for the URL.
- You can choose to handle all events under one URL or use different URLs and logins for each individual event you want monitor. If using different URLs, please list each URL and its username and password separately.
Notification Formats
Notification events will be sent via HTTP POST using basic authentication that includes username and password parameters.
Respond to the POST with a 200 HTTP Status Code to indicate to us that the notification was accepted by your web-hook. Call-Em-All will periodically retry the notification until a 200 is received or the notification expires (typically after two hours).
The notification body is JSON formatted. They contain:
- A notification section that describes the event itself. This section always has the same format.
- A payload section that contains data about the event. The format varies depending on the event-type.
See our notification events for examples.
Notification Events
Broadcast Status Change
Triggered when the status of a call or text broadcast changes to one of the following states:
| created | A broadcast has been created on your Call-Em-All account. It may be scheduled to run in the future and it may not have all the information set up to run yet. |
| ready | The broadcast has all information necessary to run and is waiting for its start time. |
| broadcasting | The broadcast started to send out phone calls or text messages. |
| completed | The broadcast has finished sending out all phone calls or text messages. |
| paused | The broadcast has been paused and no calls or texts are going out. |
| resumed | A paused broadcast resumes. |
| canceled | The broadcast was canceled. |
| expired | The window that was set up for the broadcast by the user was insufficient to send out all the calls or texts. The broadcast has been expired and some of the calls and texts are not delivered. |
Example
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Contact Authorization Change
The Contact Authorization Change event triggers when a phone number opts in or opts out to receive calls or text messages. Any time a phone number instructs Call-Em-All to stop sending texts and/or calls, or the status of The specific trigger conditions are:
- A phone number opts into receiving texts from you and your account is configured to only allow texts to phone numbers that have explicitly opted in to texts.
- A phone number opts out to receive texts from.
- A phone number that had previously opted out of your calls or texts opts back in.
Example
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
| Code | Value | Description |
|---|---|---|
| phoneNumber | String | The phone number that is changing the contacts preferences. |
| textNumber | String | Only shown if your account uses our long code text product. This is the long code phone number that your account uses to send texts. The opt in event was associated with this phone number. |
| keyword | String | Only shown if your account uses our short code text product. This is the keyword belonging to your account that the phoneNumber associated with the opt-in or opt-out. |
| contactByText | Boolean | Determines whether the phoneNumber allows contact by receiving text messages |
| contactByCall | Boolean | Determines hether the phoneNumber allows contact by receiving phone calls |
| firstName, lastName, notes | String | The contact information of the person changing the contact preferences. |
Text Message Received or Sent
The Text Message event triggers under the following conditions:
- A user on your account sends a conversation text message. This only happens for accounts that use our long code texting product.
- Call-Em-All receives an inbound text message that's directed to your account.
Example
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
| Code | Value | Description |
|---|---|---|
| textMessageID | Long | A unique identifier. |
| phoneNumber | String | The phone number to which the text was sent (outbound) or which sent the text (inbound). |
| textNumber | String | Only shown if your account uses our long code text product. This is the long code phone number that your account uses to send texts. The text message was associated with this textNumber. |
| message | String | The content of the text message. |
| messageType | String | Will be one of three values:
|
| broadcastID | Long | Optional. Inbound text message received by Call-Em-All will be classified as a "broadcast reply" if the last outbound message to phoneNumber was the result of a text broadcast. If the inbound text is so classified, then this is the broadcast ID number of the last text broadcast that contacted the phoneNumber. |
| firstName, lastName, notes | String | The contact information of the text message recipient. |