Webhooks Overview
Webhooks let you subscribe to specific events happening in your TextUs messaging account, then automatically receive updates in your application as a JSON payload whenever those events occur. After you complete the integration process and subscribe to events, you’ll continually receive real-time notifications as soon as the data is available, rather than periodically polling for data from the server with an API call.
Webhook event types
TextUs webhooks allow you to receive updates when a specific event occurs using the following event types:
| Event Type | Event Name | Description |
|---|---|---|
| Message event | message.received | An incoming message was received. |
message.delivered | An outgoing message was delivered | |
message.failed | An outgoing message failed to deliver. | |
message.unknown | An outgoing message could not be delivered due to an unknown error. | |
| Phone call event | phone_call.completed | A phone call was completed. |
| Opt out event | contact.opted_out | A contact opted out of receiving text messages. |
contact.opted_in | A contact opted in to receiving text messages. | |
| Contact event | contact.created | A contact was created |
Event notification examples
The requests below are examples of TextUs webhook events. For a full list of field definitions, see the Integrations API.
message.received
The following example shows a message.received event where a TextUs user has received an incoming message from a contact:
{
"@type": "WebhookDelivery",
"@context": "/contexts/WebhookDelivery.jsonld",
"id": "/integrations/h13Jc5/deliveries/xyz",
"timestamp": "2018-07-24T20:59:32.156Z",
"action": "message.received",
"webHook": "/integrations/h13Jc5",
"conversation": {
"@type": "Conversation",
"id": "/conversations/JYnJBY",
"@context": "/contexts/Conversation.jsonld",
"slug": "JYnJBY",
"currentState": "open",
"account": "/accounts/my_account",
"phoneNumber": "+13035551234",
"formattedPhoneNumber": "(303) 555-1234",
"accountPhoneNumber": "+13035551000",
"formattedAccountPhoneNumber": "(303) 555-1000",
"assignedContact": {
"id": "/contacts/Vled2N",
"@type": "Contact",
"@context": "/contexts/Contact.jsonld",
"name": "Anita Rodriguez",
"firstName": "Anita",
"lastName": "Rodriguez",
"phones": {
"id": "/contacts/Vled2N/phones",
"@type": "hydra:Collection",
"@context": "/contexts/hydra:Collection.jsonld",
"totalItems": 1,
"members": [
{
"@type": "ContactPhone",
"id": "/contact_phones/mxvbRw",
"@context": "/contexts/ContactPhone.jsonld",
"phoneNumber": "+13035551234",
"formattedPhoneNumber": "(303) 555-1234",
"extension": null,
"type": "Mobile",
"deliverabilityStatus": "unknown",
"contact": "/contacts/Vled2N"
}
]
},
"notes": "/contacts/DQeeO69/notes",
"conversations": "/contacts/DQeeO69/conversations",
"data": {},
"createdAt": "2020-01-06T21:49:58.312Z"
},
"associatedContacts": "/conversations/JYnJBY/associated_contacts",
"assignments": {
"@type": "hydra:Collection",
"@context": "/contexts/hydra:Collection.jsonld",
"id": "/conversations/JYnJBY/assignments",
"members": [
{
"@type": "ConversationAssignment",
"@context": "/contexts/ConversationAssignment.jsonld",
"id": "/assignments/Al4QQY",
"assignee": {
"@type": "User",
"@context": "/contexts/User.jsonld",
"id": "/users/JYnGLo",
"name": "TextUs User",
"firstName": "TextUs",
"lastName": "User",
"email": "somebody@textus.com",
"avatar": null,
"automatedActor": false
},
"assigner": "/users/JYnGLo"
}
],
"totalItems": 1
},
"participants": "/conversations/JYnJBY/participants",
"reopenConversation": null,
"closeConversation": "/conversations/JYnJBY/close",
"readConversation": "/conversations/JYnJBY/read",
"unreadConversation": "/conversations/JYnJBY/read",
"starConversation": "/conversations/JYnJBY/star",
"unstarConversation": "/conversations/JYnJBY/star",
"blockConversation": "/conversations/JYnJBY/block",
"unblockConversation": null,
"subscribeConversation": null,
"unsubscribeConversation": "/conversations/JYnJBY/subscribe",
"timeline": "/conversations/JYnJBY/timeline",
"unsubscribed": false,
"blocked": false
},
"message": {
"@type": "Message",
"id": "/messages/6Nvq9L",
"@context": "/contexts/Message.jsonld",
"direction": "outgoing",
"body": "Hi, let's set a meeting for August 14th at 2 PM.",
"formattedBody": "<div>Hi, let's set a meeting for December 14th at 2 PM.</div>",
"displayTimestamp": "2018-07-24T20:59:32.156Z",
"timelinePosition": "2018-07-24T20:59:32.156Z",
"status": "delivered",
"conversation": "/conversations/JYnJBY",
"sender": {
"@type": "User",
"@context": "/contexts/User.jsonld",
"id": "/users/JYnGLo",
"name": "TextUs User",
"firstName": "TextUs",
"lastName": "User",
"email": "somebody@textus.com",
"avatar": null,
"automatedActor": false
},
"attachments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/messages/6Nvq9L/attachments",
"members": [],
"totalItems": 0
},
"friendlyStateDescription": "Inbound Message Received"
}
}
message.delivered
The following example shows a message.delivered event where a message was successfully delivered from a TextUs user to a contact:
{
"@context": "/contexts/WebhookDelivery.jsonld",
"@type": "WebhookDelivery",
"action": "message.delivered",
"conversation": {
"@context": "/contexts/Conversation.jsonld",
"@type": "Conversation",
"account": "/accounts/pupstar-raleigh-pup",
"accountPhoneNumber": "+19842238211",
"assignContact": "/conversations/OO86d7o/assign_contact",
"assignedContact": {
"@context": "/contexts/Contact.jsonld",
"@type": "Contact",
"conversations": "/contacts/1JGnQEo/conversations",
"createdAt": "2023-11-01T14:06:38.547651Z",
"data": {
"business": "",
"tags": []
},
"firstName": "Peter",
"id": "/contacts/1JGnQEo",
"lastName": "Smith",
"name": "Peter Smit",
"notes": "/contacts/1JGnQEo/notes",
"phones": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/contacts/1JGnQEo/phones",
"members": [
{
"@context": "/contexts/ContactPhone.jsonld",
"@type": "ContactPhone",
"contact": "/contacts/1JGnQEo",
"deliverabilityStatus": "deliverable",
"extension": null,
"formattedPhoneNumber": "(925) 555-5555",
"id": "/contact_phones/oKPVZvn",
"phoneNumber": "+19255555555",
"type": "Mobile"
}
],
"totalItems": 1
}
},
"assignments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/conversations/OO86d7o/assignments",
"members": [
{
"@context": "/contexts/ConversationAssignment.jsonld",
"@type": "ConversationAssignment",
"assignee": {
"@context": "/contexts/User.jsonld",
"@type": "User",
"automatedActor": false,
"avatar": null,
"discarded": false,
"email": "slthuang@protonmail.com",
"firstName": "Stephanie",
"hasPassword": true,
"id": "/users/L7zJvw",
"lastName": "Lee",
"memberships": "/users/L7zJvw/memberships",
"name": "Stephanie Lee",
"settings": null
},
"assigner": "/users/L7zJvw",
"id": "/assignments/ngyOrVj"
}
],
"totalItems": 1
},
"associatedContacts": "/conversations/OO86d7o/associated_contacts",
"blockConversation": "/conversations/OO86d7o/block",
"blocked": false,
"closeConversation": "/conversations/OO86d7o/close",
"currentState": "open",
"formattedAccountPhoneNumber": "(984) 223-8211",
"formattedPhoneNumber": "(925) 555-5555",
"id": "/conversations/OO86d7o",
"latestPreviewableItem": "/messages/88q4091",
"participants": "/conversations/OO86d7o/participants",
"phoneNumber": "+19257088515",
"readConversation": "/conversations/OO86d7o/read",
"reopenConversation": null,
"requestingUserInfo": "/conversations/OO86d7o/user_info",
"slug": "OO86d7o",
"starConversation": "/conversations/OO86d7o/star",
"stats": "/conversations/OO86d7o/stats",
"subscribeConversation": null,
"timeline": "/conversations/OO86d7o/timeline",
"unanswered": true,
"unblockConversation": null,
"unreadConversation": "/conversations/OO86d7o/read",
"unstarConversation": "/conversations/OO86d7o/star",
"unsubscribeConversation": "/conversations/OO86d7o/subscribe",
"unsubscribed": false
},
"id": "/integrations/LmKXZl/deliveries/6ZKqx04",
"message": {
"@context": "/contexts/Message.jsonld",
"@type": "Message",
"attachments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/messages/88q4091/attachments",
"members": [],
"totalItems": 0
},
"body": "Hi, let's schedule a follow up after your meeting for 1:30 PM. How's that sound?",
"conversation": "/conversations/OO86d7o",
"deliveryState": "delivered",
"direction": "out",
"displayTimestamp": "2023-11-17T18:59:04.568354Z",
"flags": [
"auto_message",
"auto_reply_message"
],
"formattedBody": "<p>Hi, let's schedule a follow up after your meeting for 1:30 PM. How's that sound?</p>",
"friendlyStateDescription": "Message Delivered",
"id": "/messages/88q4091",
"latestEventAt": "2023-11-17T18:59:07.008155Z",
"retry": null,
"retryAllowed": false,
"sender": {
"@context": "/contexts/User.jsonld",
"@type": "User",
"automatedActor": true,
"avatar": "/icon-192x192.png",
"discarded": false,
"email": "support@textus.com",
"firstName": "TextUs",
"hasPassword": false,
"id": "/users/BYoaNE",
"lastName": "Bot",
"memberships": "/users/BYoaNE/memberships",
"name": "TextUs Bot",
"settings": null
},
"source": "textus",
"status": "delivered",
"timelinePosition": "2023-11-17T18:59:04.568354Z"
},
"timestamp": "2023-11-17T13:59:04.568354-05:00",
"webHook": "/integrations/LmKXZl"
}
contact.opted_out
The following example shows a contact.opted_out event where a TextUs contact has opted out of receiving text messages:
{
"@type": "OptOutWebhookDelivery",
"@context": "/contexts/OptOutWebhookDelivery.jsonld",
"id": "/integrations/KYxmBL/deliveries/f8db6d71-04bd-47cb-9983-d6fd2015ce3b",
"action": "contact.opted_out",
"timestamp": "2021-07-27T18:48:16.878086+00:00",
"webHook": "/integrations/KYxmBL",
"optOut": {
"@type": "OptOut",
"@context": "/contexts/OptOut.jsonld",
"id": "/textus/opt_outs/50711",
"type": "opt-out",
"phoneNumber": "+15551234567",
"formattedPhoneNumber": "(555) 123-4567",
"account": "/accounts/textus"
}
}
contact.created
The following example shows a contact.created event where a TextUs user has created a new contact:
{
"@type": "ContactWebhookDelivery",
"@context": "/contexts/ContactWebhookDelivery.jsonld",
"id": "/integrations/BYoaNE/deliveries/b3d91245-9658-4d3b-a855-a524151cd02d",
"action": "contact.created",
"timestamp": "2021-07-27T15:42:44.359180+00:00",
"webHook": "/integrations/BYoaNE",
"contact": {
"@type": "Contact",
"@context": "/contexts/Contact.jsonld",
"id": "/contacts/ZNZD6Y",
"name": "Jane Soto",
"firstName": "Jane",
"lastName": "Soto",
"phones": {
"@type": "hydra:Collection",
"@context": "/contexts/hydra:Collection.jsonld",
"id": "/contacts/ZNZD6Y/phones",
"members": [
{
"@type": "ContactPhone",
"@context": "/contexts/ContactPhone.jsonld",
"id": "/contact_phones/9Na06L",
"phoneNumber": "+15551234567",
"formattedPhoneNumber": "5551234567",
"extension": null,
"type": "Mobile",
"deliverabilityStatus": "unknown",
"contact": "/contacts/ZNZD6Y"
}
],
"totalItems": 1
},
"notes": {
"@type": "hydra:Collection",
"@context": "/contexts/hydra:Collection.jsonld",
"id": "/contacts/ZNZD6Y/notes",
"members": [],
"totalItems": 0
},
"conversations": "/contacts/ZNZD6Y/conversations",
"data": {
"tags": [],
"business": "Example Organization"
},
"createdAt": "2021-07-27T15:42:44.086511Z"
}
}