Reporting Webhooks
Receive Regal real-time events to any endpoint
Reporting Webhooks send real-time activity events (e.g. contact.subscribed, sms.sent, call.completed) as JSON in an HTTP POST to an endpoint of your choosing.
Enable Reporting Webhooks
To set up Reporting Webhooks,
- Go to the Regal app > Settings page.
- In the section labeled "Reporting Webhooks", click "Create Webhook."
- Enter the URL of the endpoint you'd like us to send events to and enter an API Key for the endpoint, if one is required. Then click "Save"
To test that the endpoint is receiving events, you can navigate to the Agent Desktop and change your activity status in the top right dropdown to a different status. You should receive an agent.activity.updated event.
Create Webhook
Updating an Endpoint
When you edit an endpoint, it can take up to 5 minutes for the cache to refresh and start sending events to your new endpoint instead.
Retries
Currently there are no retries on these events. If a response is not received within 1 second, the event is dropped and not retried. We will be adding retries in a future release.
Events
Regal publishes the following events to the Reporting Webhooks:
| Event Name | Description |
|---|---|
| agent.activity.updated | An agent’s activity status was changed |
| call.completed | An inbound or outbound call with a contact was completed. This includes calls that were not answered |
| call.recording.available | A call recording link is available |
| cancel.all.automated.tasks | An agent cancels all automated tasks of a contact from the agent desktop |
| contact.attribute.edited | A contact’s attributes were edited by an agent |
| contact.created | A contact was created in your Regal account |
| contact.experiment.assigned | A contact was assigned to an experiment |
| contact.subscribed | A contact was subscribed to a marketing channel |
| contact.unsubscribed | A contact was unsubscribed from a marketing channel |
| contacted.after.hours | A contact texted or called in outside of business hours |
| mms.received | An mms was received from a contact (inbound) |
| mms.sent | An mms was sent from Regal to contact (outbound) |
| scheduled.reminder.created | An agent scheduled a reminder |
| scheduled.callback.requested | An agent schedules a callback |
| sms.conversation.completed | An SMS conversation between a contact and an agent was completed in the Regal agent desktop |
| sms.queued | An sms was queued to be sent from Regal to contact (outbound) |
| sms.received | An sms was received from a contact (inbound) |
| sms.sent | An sms was sent from Regal to contact (outbound) |
| sms.undelivered | An sms was undelivered from Regal to contact (outbound) |
| task.canceled | A call or sms task was canceled |
| task.created | A call or sms task was created |
| task.reservation.accepted | A reservation was accepted by an agent |
| task.reservation.created | A reservation was created for a task |
Event Properties
Below are the properties and definitions included in Regal events.
| Property Name | Description | Data Type |
|---|---|---|
| agent_activity_name | Name of agent’s new availability status | string |
| agent_availability | Availability of agent’s previous activity status. Can be true or false | boolean |
| agent_email | Email of the agent who took an action | string |
| agent_previous_activity_name | Name of agent’s previous availability status | string |
| agent_previous_availability | Availability of agent’s previous activity status. Can be true or false | boolean |
| agent_time_in_previous_activity | Time (in seconds) agent spent in previous activity status | integer |
| call_id | Task Id for the call | string |
| campaign_id | Campaign UUID | string |
| campaign_friendly_id | Campaign Friendly Id as seen in the App | integer |
| campaign_name | Campaign Name | string |
| cancelation_reason | Reason the task was canceled | string |
| cancelation_source | Source of where the task was canceled | string |
| canceled_by | Includes the email of the user who canceled the task, if applicable | string |
| changes | Changes made for the contact.attribute.edited event; includes name of attribute edited with the "old_value" and "new_value" | object |
| channel | The marketing channel: “voice” or “sms” | string |
| completed_at | UTC Timestamp when the task was completed | UTC timestamp |
| contact_phone | Phone number of the contact | string |
| content | In sms events: Content of the message In sms.conversation events: Contents of the conversation | string in sms.queued, sms.sent, sms.undelivered and sms.received events array in sms.conversation.completed event |
| direction | INBOUND or OUTBOUND | string |
| disposition | Task disposition | string |
| The last email associated with the contact | string | |
| ended_at | UTC timestamp when the conversation was ended | timestamp |
| experiment_id | Experiment ID | integer |
| experiment_name | Name of experiment | string |
| experiment_variant | Variant a contact was assigned to in an experiment | string |
| from_number | Phone number that sent the message | string |
| handle_time | Full duration task was being handled, including talk time and wrap time (completed_at - started_at) | integer |
| ip | The IP address from where the subscription update was initiated | string |
| media_url | Media URL (for MMS) | string |
| notes | Task notes | string |
| objections | Task tags | array |
| phone | Same as contact_phone | string |
| queue | Name of task queue | string |
| recording_link | Call recording link | string |
| regal_voice_phone | Regal phone number | string |
| regal_voice_phone_internal_name | Internal name of phone line displayed to agents | string |
| reserved_agent_email | Email of the agent the task reservation is for | string |
| reserved_agent_fullname | Full name of the agent the task reservation is for | string |
| scheduling_agent_fullname | Full name of the agent who scheduled the Callback | string |
| scheduling_agent_id | Email of the agent who scheduled the Callback | string |
| sms_conversation_id | Task ID for the conversation. (If the sms was part of a two-way conversation with an Agent, rather than just an automated outbound sms) | string |
| source | Source of the subscription update. A source value that starts with “Brand.” indicates that the subscription update was initiated by the Brand (outside of the Regal platform). A source value that starts with “Regal.” indicates that the subscription update was initiated through the Regal platform. | string |
| started_at | UTC timestamp when the conversation was started | UTC timestamp |
| talk_time | Duration of conversation (ended_at - started_at) | integer |
| target_agent_fullname | Full name of the agent who contact (and all contact’s tasks) are assigned to | string |
| target_agent_id | Email of the agent who contact (and all contact’s tasks) are assigned to | string |
| task_id | Unique identifier for the task. Will match the call_id or sms_conversation_id of a completed task event | string |
| text | The exact text the contact was presented for opt in | string |
| timestamp | Unix timestamp for when the event took place | unix timestamp |
| to_number | Phone number to which the message was sent | string |
| type | Task Type (e.g., Outbound SMS, Outbound Call, Scheduled Callback) | string |
| wrapup_time | Duration task was in wrap up (completed_at - ended_at) | integer |
Event Schema
Events from Reporting Webhooks follow the below schema:
{
"userId": "123",
"originalTimestamp": "1636666068",
"traits":{"email": "[email protected]", "phone": "+17625551796"},
"name": "event.name",
"properties": {
"property": "value1",
"property2": "value2",
…},
"eventSource": "Regal Voice"
}
agent.activity.updated
{
"name": "agent.activity.updated",
"properties": {
"agent_email": "[email protected]",
"agent_activity_name": "Offline",
"agent_availability": false,
"agent_previous_activity_name": "Available",
"agent_previous_availability": true,
"agent_time_in_previous_activity": "3829"
},
"originalTimestamp": "1657836812",
"eventSource": "Regal Voice"
}
call.completed
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "call.completed",
"properties": {
"agent_firstname": "Rebecca",
"agent_fullname": "Rebecca Greene",
"agent_id": "[email protected]",
"direction": "OUTBOUND",
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Sales Line",
"contact_phone": "+176255517965",
"call_id": "WTxxxxx9",
"type": "Outbound Call",
"disposition": "Converted During Convo",
"notes": null,
"objections": null,
"campaign_name": "Life Insurance Quote Follow Up",
"campaign_friendly_id": "445",
"started_at": 1657855046,
"ended_at": 1657855053,
"completed_at": 1657855059,
"talk_time": 7,
"wrapup_time": 6,
"handle_time": 13,
"journey_uuid": null,
"journey_name": null,
"journey_friendly_id": null
},
"originalTimestamp": "1657855059",
"eventSource": "Regal Voice"
}
call.recording.available
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "call.recording.available",
"properties": {
"agent_email": "[email protected]",
"direction": "OUTBOUND",
"regal_voice_phone": "+19032823158",
"regal_voice_phone_internal_name": "Acquisition Line",
"contact_phone": "+13523182825",
"call_id": "WT953358e8822dd9333fc38dfbac25e1e1",
"type": "Outbound Call",
"disposition": "Converted On Call",
"notes": "The customer was just confirming pricing. Said pricing was unclear on our iOS app.",
"objections": ["Pricing"],
"campaign_name": "Abandoned Cart",
"campaign_friendly_id": "13",
"recording_link": "https://api.twilio.com/2010-04-01/Accounts/ACxxx/Recordings/xxx.mp3",
"started_at": 1657799128,
"ended_at": 1657799136,
"talk_time": 8,
"journey_uuid": "xxx-xxx-xxx-xxxx",
"journey_name": "Welcome Journey",
"journey_friendly_id": 130
},
"originalTimestamp": "1657843308",
"eventSource": "Regal Voice"
}
cancel.all.automated.tasks
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "cancel.all.automated.tasks",
"properties": {
"campaign_friendly_id": 445,
"canceled_by": "[email protected]",
"cancelation_source": "Agent Desktop",
"original_task_id": "WTxxxxxx",
"timestamp": "1657855043"
},
"originalTimestamp": "1657855043",
"eventSource": "Regal Voice"
}
contact.attribute.edited
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]",
},
"name": "contact.attribute.edited",
"properties": {
"agent_email": "[email protected]",
"contact_phone": "+17625551796",
"changes": {
"custom_properties": {
"annual_income": {
"old_value": "150,000",
"new_value": "300,000"
}
}
},
"created_at": "1657855462"
},
"originalTimestamp": "1657855462",
"eventSource": "Regal Voice"
}
contact.created
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "contact.created",
"properties": {
"contactPhone": "+17625551796",
"email": [email protected],
"firstName": Katherine,
"lastName": TheGreat
},
"originalTimestamp": "1657839234",
"eventSource": "Regal Voice",
}
contact.experiment.assigned
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]",
},
"name": "contact.experiment.assigned",
"properties": {
"experiment_name": "Post Call Offer Test",
"experiment_id": "xxxx-xxxx-xxxx-xxxx",
"experiment_variant": "Aggressive Offer - 50%",
"journey_uuid": "xxxx-xxxx-xxxx-xxxx",
"journey_friendly_id": 220,
"journey_name": "Post Call Follow Up"
},
"originalTimestamp": "1657855118",
"eventSource": "Regal Voice"
}
contact.subscribed
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]",
"ip": "78.97.213.166"
},
"name": "contact.subscribed",
"properties": {
"new_subscription": true,
"channel": "voice",
"text": "By clicking “Next”, I agree to receive automated marketing, including calls and recurring text messages from Circle Bank at the telephone number provided. Consent is not a condition of purchase. Reply HELP for help and STOP to cancel. Msg & data rates may apply.*",
"ip": "78.97.213.166",
"source": "circle-bank.booking_flow",
"timestamp": "1611245052"
},
"originalTimestamp": "1657839189",
"eventSource": "Regal Voice"
}
}
contact.unsubscribed
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]",
"ip": "78.97.213.166"
},
"name": "contact.unsubscribed",
"properties": {
"new_subscription": true,
"channel": "voice",
"text": null,
"ip": "207.38.149.143",
"source": "regalvoice.agent_desktop",
"timestamp": "1657855229"
},
"originalTimestamp": "1657855230",
"eventSource": "Regal Voice"
}
scheduled.reminder.created
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]",
},
"name": "scheduled.reminder.created",
"properties": {
"scheduling_agent_email": "[email protected]",
"contact_phone": "+17625551796",
"originating_task_id": "WTxxxx",
"scheduled_at": "2022-07-16T14:00:00.000-04:00",
"notes_from_agent": "Remember to email the insurance form.",
"timezone": "America/New_York",
"regal_voice_phone": "+19545558563"
},
"originalTimestamp": "1657863441",
"eventSource": "Regal Voice"
}
scheduled.callback.requested
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]",
},
"name": "scheduled.callback.requested",
"properties": {
"scheduling_agent_email": "[email protected]",
"scheduling_agent_fullname": "Rebecca Greene",
"contact_phone": "+17625551796",
"callback_timestamp ": "2022-07-13 14:00:00 -07:00",
"notes_from_agent": "The customer was excited to chat but was on the road.",
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Retention Line",
"originating_task_id": "WTxxxx",
"callback_friendly_date": "07/13/2022",
"callback_friendly_day": "Wednesday",
"callback_friendly_time": "02:00 PM",
"callback_friendly_timezone": "Pacific Time",
"callback_friendly_timestamp": "Wednesday 07/13/2022 at 02:00 PM Pacific Time"
},
"originalTimestamp": "1657863426",
"eventSource": "Regal Voice"
}
sms.conversation.completed
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "sms.conversation.completed",
"properties": {
"content": [
[
"2022-07-15 03:17:50",
"Agent",
"sent",
"Hi there, I see you're looking to cancel. Can I ask why?"
],
[
"2022-07-15 03:19:49",
"Contact",
"received",
"Yeah - it hasn't been the right fit for my pup."
],
[
"2022-07-15 03:19:58",
"Agent",
"sent",
"Let's hop on a call quickly so I can help out! ☺️"
]
],
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Retention Line",
"contact_phone": "+176255517965",
"sms_conversation_id": "WTxxxxxx",
"agent_id": "[email protected]",
"agent_firstname": "Rebecca",
"agent_fullname": "Rebecca Greene",
"direction": "OUTBOUND",
"type": "Outbound SMS",
"disposition": "Interested",
"objections": ["Product Issues"],
"notes": "Dog was having stomach issues after eating the all-fish plan. Changed up plan and extended trial 2 months.",
"started_at": 1657855067,
"ended_at": 1657855198,
"completed_at": 1657855211,
"talk_time": 600,
"wrapup_time": 13,
"handle_time": 144,
"journey_uuid": null,
"journey_name": null,
"journey_friendly_id": null
},
"originalTimestamp": "1657855211",
"eventSource": "Regal Voice"
}
Content Property on Automated SMS Events
The content property is available on all sms events from automated sms triggered by journeys, but originates from the sms.queued event. In up to ~.05% of cases, the content field may not populate on sms.sent events from automated sms due to sms.queued and sms.sent events coming out of order, so if you need to trigger build reporting off of the content property, rely on the sms.queued events for that.
sms.queued
/ This this is an automated sms example./
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "sms.queued",
"properties": {
"direction": "OUTBOUND",
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Sales Line",
"contact_phone": "+17625551796",
"from_number": "+19545558563",
"to_number": "+17625551796",
"sms_message_id": "SMxxxxxxx",
"campaign_id": "xxx-xxx-xxx-xxx",
"campaign_friendly_id": "2",
"campaign_name": "Welcome",
"journey_uuid": "xxx-xxx-xxx-xxx",
"journey_name": "Welcome Journey",
"journey_friendly_id": 211,
"content": "Circle Bank: Thanks for signing up for a new savings account. Can I help you fund your account?",
"media_url": null
},
"originalTimestamp": "1657846990",
"eventSource": "Regal Voice"
}
sms.received
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "sms.received",
"properties": {
"agent_fullname": "Rebecca Greene",
"agent_id": "[email protected]",
"direction": "INBOUND",
"content": "Hey thx for messaging me ☺️ ",
"media_url": null,
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Sales Line",
"contact_phone": "+17625551796",
"from_number": "+19545558563",
"to_number": "+17625551796",
"sms_conversation_id": "WTxxxx",
"sms_message_id": "IMxxxx"
},
"originalTimestamp": "1657855189",
"eventSource": "Regal Voice"
}
sms.sent
/ This this is an agent-sent sms example./
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "sms.sent",
"properties": {
"agent_fullname": "Rebecca Greene",
"agent_id": "[email protected]",
"direction": "OUTBOUND",
"content": "any time! 😎",
"media_url": null,
"regal_voice_phone": "+19545558563",
"contact_phone": "+17625551796",
"from_number": "+19545558563",
"to_number": "+17625551796",
"sms_conversation_id": "WTxxxxx",
"sms_message_id": "IMxxxxx"
},
"originalTimestamp": "1657855198",
"eventSource": "Regal Voice"
}
sms.undelivered
/ This this is an automated sms example./
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "sms.undelivered",
"properties": {
"direction": "OUTBOUND",
"regal_voice_phone": "+19545558563",
"contact_phone": "+17625551796",
"from_number": "+19545558563",
"to_number": "+17625551796",
"sms_message_id": "SMxxxx",
"campaign_id": "xxx-xxx-xxx-xxx",
"campaign_friendly_id": "2",
"campaign_name": "Welcome",
"journey_uuid": "xxx-xxx-xxx-xxx",
"journey_name": "Welcome Journey",
"journey_friendly_id": 211,
"content": "Circle Bank: Thanks for signing up for a new savings account. Can I help you fund your account?",
"media_url": null
},
"originalTimestamp": "1657846990",
"eventSource": "Regal Voice"
task.canceled
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "task.canceled",
"properties": {
"direction": "OUTBOUND",
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Retention Line",
"contact_phone": "+176255517965",
"task_id": "WTxxxxxxx",
"type": "Outbound Call",
"campaign_name": "Post-purchase Call",
"campaign_friendly_id": "393",
"queue": "Outbound Call",
"channel": "voice",
"target_agent_fullname": "Rebecca Greene",
"target_agent_id": "xxx.yourbrand.com",
"canceled_by": "regal_voice",
"cancelation_reason": "task_timeout",
"cancelation_source": "system",
"cancelation_notes": null,
"journey_uuid": "xxx-xxx-xxx-xxxx",
"journey_name": "Welcome Journey",
"journey_friendly_id": 130
},
"originalTimestamp": "1657839466",
"eventSource": "Regal Voice"
}
task.created
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "task.created",
"properties": {
"target_agent_fullname": "Rebecca Greene",
"target_agent_id": "[email protected]",
"scheduling_agent_fullname": null,
"scheduling_agent_id": null,
"direction": "OUTBOUND",
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Retention Line",
"contact_phone": "+176255517965",
"task_id": "WTxxxxxxxx",
"type": "Outbound Call",
"campaign_name": "Post-purchase Call",
"campaign_friendly_id": "393",
"queue": "Outbound Call",
"channel": "voice",
"journey_uuid": "xxx-xxx-xxx-xxxx",
"journey_name": "Welcome Journey",
"journey_friendly_id": 130
},
"originalTimestamp": "1657839344",
"eventSource": "Regal Voice"
}
task.reservation.accepted
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "task.reservation.accepted",
"properties": {
"target_agent_email": null,
"scheduling_agent_fullname": null,
"scheduling_agent_email": null,
"reserved_agent_email": "[email protected]",
"reserved_agent_fullname": "Rebecca Greene",
"direction": "OUTBOUND",
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Retention Line",
"contact_phone": "+176255517965",
"task_id": "WTxxxxxxx",
"type": "Outbound SMS",
"campaign_name": null,
"campaign_friendly_id": null,
"queue": "Outbound SMS",
"channel": "sms",
"journey_uuid": null,
"journey_name": null,
"journey_friendly_id": null
},
"originalTimestamp": "1657855220",
"eventSource": "Regal Voice"
}
task.reservation.created
{
"userId": "123",
"traits": {
"phone": "+17625551796",
"email": "[email protected]"
},
"name": "task.reservation.created",
"properties": {
"target_agent_email": null,
"scheduling_agent_fullname": null,
"scheduling_agent_email": null,
"reserved_agent_email": "[email protected]",
"reserved_agent_fullname": "Rebecca Greene",
"direction": "OUTBOUND",
"regal_voice_phone": "+19545558563",
"regal_voice_phone_internal_name": "Retention Line",
"contact_phone": "+176255517965",
"task_id": "WTxxxxxxx",
"type": "Inbound SMS",
"campaign_name": null,
"campaign_friendly_id": null,
"queue": "Outbound SMS",
"channel": "sms",
"journey_uuid": null,
"journey_name": null,
"journey_friendly_id": null
},
"originalTimestamp": "1657836811",
"eventSource": "Regal Voice"
}
Updated 2 months ago