Each Telerivet project can have multiple automated services that handle incoming messages. You might have one service to handle certain keywords (such as a subscription service or a keyword-based auto-reply), while you might have another service to handle all messages (such as a webhook that forwards messages to your own server), or to handle all messages that aren't handled by another service.
When an incoming message is received, Telerivet typically applies services from top to bottom as listed on the Incoming Message tab on the Services page. To change the order of your active services, click and drag the icon in the left column for any active service in the Incoming Message tab:
Note that the drag handle is only visible if your project has multiple active services that handle incoming messages, and is only available on the Active tab for services triggered via Incoming Message when the Summary view is selected. The drag handle will also be unavailable if the Services table is sorted by any other column.
Handling Messages
If one service "handles" an incoming message, then Telerivet will not try applying any subsequent services for that message.
By default, Telerivet will consider a service to have "handled" the message if it performs any the following actions:
- Sending an SMS message
- Adding or removing a group member
- Answering a poll question
- Setting the return_value variable to 1 (Custom Actions, Cloud Script API, or Webhook API)
This behavior allows you to have multiple services that handle different messages. For example, you could have:
- A webhook service at the top that forwards all messages to your own server (but doesn't send replies)
- A SMS poll to collect feedback about customer service
- A subscription service that handles keywords like "JOIN" and "STOP"
- An auto-reply service that handles keywords like "HOURS" or "COUPON"
- A catch-all service at the bottom that sends an auto-reply if someone sends an unknown keyword
Using the algorithm above for determining when a service has handled a message, receiving the message "JOIN" would cause Telerivet to perform the following actions:
- Send the message to the webhook URL on your server; since it doesn't send a reply it would continue to the next service
- Test if "JOIN" is accepted as a valid response to the SMS poll and if the contact is allowed to participate in the poll; if so, interpret it as a poll response and stop; otherwise, continue to the next service
- Perform the actions for the "JOIN" keyword on the subscription service, by adding the contact to a subscribers group and sending an auto-reply. Since an SMS message was sent (and a contact was added to a group), the message is marked as "handled", so Telerivet will stop there without applying the other services. By stopping, service 5 will not send a message saying that the keyword is invalid.
Although this is rarely needed, you can manually set the return_value variable to 0 (in the Rules Engine, Cloud Script API, or Webhook API), which will allow Telerivet to continue processing services for that message, even if the service performed an action that "handled" the message.
Overriding Top-to-Bottom Order
Telerivet will override the top-to-bottom order of service execution for a particular contact if a particular service is "waiting" for a response, or more precisely, when a contact has "state" for a particular service. Any services where a contact has "state" will be tried first, in order of the most recent time that service was applied for that contact.
Telerivet overrides the top-to-bottom order of services in several situations:
- whenever a contact triggers a "Wait for response" action
- if you manually set the "state.id" variable within a custom service
- when a contact is in process of answering a poll
For example, if you send a poll to a particular contact, Telerivet will remember that the contact is currently answering question "q1" of that particular poll, so it will assume that the contact's response is a response to the poll.
Usually, this intuitively does what you want. For example, suppose you have multiple SMS polls active at the same time. If you send someone an SMS poll and someone replies, the message should be interpreted as a response to the SMS poll you actually sent them, not the poll which happened to be listed first on your Services page.