Notify Chatitive that a subscriber event has occurred.
Subscriber events trigger workflow execution for workflows that are configured to listen for the specific events. The subscriber event mechanism provides gives multiple workflows the opportunity to handle the system event. By utilizing specific start conditions, the actual workflows that handle the event can be customized to the subscriber and event details.
Note that either phone_number or subscriber_sid must be specified to identify the subscriber for whom the event has occurred.
Subscriber events can also manage new phone numbers to the channel. The parameters allow_new and subscribe_new provide fine-grain control over how new phone numbers are treated by the event publication API. When a new phone number to the channel is specified and allow_new = true, a new subscriber will be created on the channel before any workflows are invoked. The subscriber is created with status unconfirmed. Additionally, if subscribe_new = true the new subscriber will be subscribed to the system with status subscribed.
Choosing to subscribe new phone numbers depends on the use-case. Typically, the subscribed status indicates that the subscriber has explicitly opted-in to messaging and accepted legal terms and conditions related to messaging. If the publication of an event invokes a workflow that presents the user with legal terms and the option to subscribe to the channel, the event should be published with allow_new = true and subscribe_new = false. The workflow can then manage the subscription status.
However, if the subscriber has already expressed consent and the published event represents the first time that Chatitive has seen the phone_number on the channel, it is acceptible to publish the event with allow_new = true and subscribe_new = true. Because subscriber status is used to manage legal compliance, do not hesitate to reach out to your Chatitive representitive with questions on how to manage it.
When allow_new = false and a new phone number is received, nothing happens i.e. the event is ignored.
Utilize the payload parameter to pass details of the event to workflows as workflow kwargs (keyword arguments). These arguments can be used to build start conditions, create custom messaging, set properties, and add subscribers to groups. In the sample below, ticket_id, ticket_status, and cs_agent_name will all be available to any workflow that is triggered by the event.
Such a workflow might have a start condition as follows,
ticket_status equals 'Success'
Which restricts the workflow from executing for tickets that were not sucessfully resolved. That workflow might send the following message, requesting feedback,
Hi {{ subscriber.properties.firstName }},
We'd appreciate any feedback on your recent support interaction with {{ cs_agent_name }}. You can just reply to this message.
More information about your support request is available at {{ ticket_url }}.
Have a great day!
Notice that the payload keys are available as workflow arguments. Complex objects (nested hashes) are valid values for workflow and event payload arguments.
| Response format | JSON |
|---|---|
| Requires authentication? | Yes |
event_name required | The name of the event being notified. Note that this value must match exactly what is configured on the workflow start conditions. |
|---|---|
phone_number optional | The phone number of the subscriber for whom the event has occurred. Either phone_number or subscriber_sid must be specified. |
subscriber_sid optional | The unique identifier of the subscriber for whom the event has occurred. Either phone_number or subscriber_sid must be specified. |
allow_new optional | Boolean indicating that a new phone number to the channel should add a new subscriber. Default is |
subscribe_new optional | Boolean indicating that a new phone number to the channel should subscribe the new subscriber. By default, new subscribers are added with status |
payload optional | The event payload. This dictionary directly available within workflow execution for use in start conditions, message building, property setting, etc. |
curl \
-X POST \
-u '[SID]:[TOKEN]' \
-H 'Content-Type: application/json' \
-d '{ "event_name": "RequestSupportFeedback", "phone_number": "555-555-5555", "allow_new": false, "subscribe_new": false, "payload": { "ticket_url": "https://support.yourcompany.com/tickets/12345", "ticket_status": "Success", "cs_agent_name": "Pam" } }' \
'https://api.essential.to/v2/account/channels/p03Gjl8Uzn0RkZSpHXHnrw/subscribers/events/notify'
# Sample response
202 Accepted
Python coming soon.
Node coming soon.