Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Using States and Timers in Conversations

Public Beta

Twilio's Conversations API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.

Public Beta products are not covered by a Twilio SLA.

With Twilio Conversations' states and timers features, you can manage, store, and archive your application's Conversations.

By using these features, your Conversations participants can focus on active (ongoing) Conversations. You can also close out old or inactive Conversations to make sure you're not exceeding the Participants-per-Conversation limit.

This guide provides an overview to states and timers, as well as how to configure them.

For the best end-user experience, we highly recommend that you read the complete Twilio Conversations documentation and tailor our general recommendations provided for your specific use case.

Note: The Conversation States and Timers are only modifiable via the REST API.

What are states and timers in Conversations?

Conversations States and Timers are a default feature which appear in a Conversation's Properties.

There are two configurable timers to automatically transition Conversations between active to inactive as well as from inactive to closed states.

states_timers_general

Note: We recommend leaving the default Conversation state as active unless you need to change it for your specific use case.

There are three ways to transition between Conversations states:

  1. Use a configured timer (see below). The state will change once the timer elapses.
  2. Manipulate state using a REST API call.
  3. The Conversation will automatically move from an inactive to active state when a new text or media message arrives.

Conversation States

A Conversation can have one off three states:

  • active
  • inactive
  • closed

Active and Inactive Conversations

A newly created Converation has the active state by default. Active and inactive states are considered as "hot" storage and can be easily manipulated back and forth. The transition between these two states is instantaneous; there will be no delay.

Be aware that active and inactive conversations count towards the participant-per-conversation limit: 50 non-Chat (SMS, WhatsApp, etc) and up to 1000 native Chat participants.

        
        
        
        
        This code sample transitions a Conversation from the active to inactive state

        Update a Conversation's state

        This code sample transitions a Conversation from the active to inactive state

        Closed Conversations

        The closed state is a little bit more special: once a Conversation is closed, it cannot be restarted. In other words, you cannot add new Participants to a Conversation in the closed state.

        If new message comes into closed Conversation, a new Conversation will be auto-created with the Participant who initiated the Conversation. At this point, there is no automatic addition of other Participants, so you should add them to the newly created Conversation.

        Be aware that closed Conversations do not count towards the Participant-per-Conversation limit.

        Conversations Timers

        There are no default timers configured at the time of account creation. Instead, you choose whether or not to set timers for individual Conversations.

        There are two configurable timers to transition between Conversation states:

        • timers.inactive
        • timers.closed

        Timers are optional functionality, but we highly recommend enabling them to manage Conversations efficiently. Setting timers allows you to see the specific date and times when a Conversation transitions between activate and inactive as well as inactive and closed states.

        All timer values are represented in ISO 8601 duration format.

        In the following example, the Conversation has two timers set:

        "timers": {
            "date_inactive": "2015-12-16T22:19:38Z",
            "date_closed": "2015-12-16T22:28:38Z"
        }
        

        Note: If you wish to disable one or both timers, use PT0S to set them to zero.

        A few things to be aware of when configuring Conversations Timers:

        • If both timers are set, they automatically support active-to-inactive and inactive-to-closed transitions
        • Timers have precision of one second (1 second)
        • The minimum time for inactive timer is 60 seconds (one minute). For a closed timer, the minimum time is 600 seconds (ten minutes).
        • When you manually change the state of a Conversation, for example by REST API call, the timer counter resets to zero.
              
              
              
              
              Set the inactive and closed timers on a specific Conversation

              Create timers for a Conversation

              Set the inactive and closed timers on a specific Conversation

              Use case examples for Conversations States and Timers

              At their core, states and timers in Conversations provide basic functionality to handle customers' requests promptly and to better manage time for service provider, such as customer service agents, tutors, healthcare workers, and wealth advisors.

              Examples of how to use states and timers include:

              Handling inbound contacts from your customers

              To handle inbound customer contacts, we recommend setting the inactive timer to roughly the human attention span, or a few minutes. This way, the person fielding the inbound requests can stay focused and manage the incoming messages more efficiently. Once the inactive timer has elapsed on a given Conversation, the new active Conversation kicks in, waiting for a response.

              To determine the timer for transitioning to the closed state, determine the length of your average conversation; this is the best indicator for how long to wait before an inactive Conversation should be archived and moved to closed state.

              Building and managing long-term relationships with customers

              Some use cases involve long-term relationships with your customers, such those that a wealth manager or a personal shopper develops. In this case, you can use primarily inactive timers. Ideally, Conversations go to the closed state after years--rather than minutes--of inactivity so that customers are assured that their important conversations are handled with care.

              Consider the following four scenarios for how to configure states and timers

              Scenario #1: Both timers are configured

              With the following settings, the Conversation's state changes to inactive if there has been no update for 300 seconds. At this point, the clock on timers.closed starts to tick. If after 30,000 seconds, there is still no activity, the clock on timers.closed elapses, and the Conversation state changes to closed.

              • set timers.inactive = 300 seconds
              • set timers.closed = 30,000 seconds

              Scenario #2: No timers configured

              In this case, the Conversation's state never changes to inactive because the timers.inactive property has not been set. Likewise, the clock on timers.closed never starts to increment because timers.closed was also not configured. The Conversation's state is always active.

              • set timers.inactive = not configured
              • set timers.closed = not configured

              Scenario #3: Only inactive timer configured

              With these settings, the Conversation never transitions to the closed state because timers.closed is not configured. The Conversation's state becomes inactive if there has been no updating activity for 600 seconds; inactive is the last possible state that the Conversation can have.

              Please note: Because this Conversation never achieves the closed state, it will be always counted into Conversation-per-User limit.

              • set timers.inactive = 600 seconds
              • set timers.closed = not configured

              Scenario #4: Only closed timer configured

              With these settings, the Conversation never becomes inactive because timers.inactive is not set. The Conversation's state is remains active for its entire duration. Finally, timers.closed closes the Conversation after 30 days from the moment it was created. The Conversation will be transitioned automatically to state closed after 30 days, regardless of activity. (This means even if there are new text or media messages, the Conversation will still change to the closed state.)

              • set timers.inactive = not configured
              • set timers.closed = 30 days

              Currently, you can only control the post-webhook onConversationStateUpdated via the REST API.

              Best practices for States and Timers configuration

              With Conversations, there is no need to set any default state. All Conversations are in an active state as soon as they are created.

              We advise setting your timers and state transitions based on your unique use case, taking into account your end users' behavior and the number of Conversations you expect to create. Based on analysis of Conversations data, we suggest the following "rule of thumb" as common values that will work for timers in many use cases:

              • Transition to inactive after 30 days of inactivity in active state
              • Transition to closed after one (1) year in the inactive state with no activity (new text or media messages)

              Keep in mind that your use case may benefit from shorter timers, but the above suggestions are a good starting place.

              What's Next?

              Setting states and timers for your Conversations helps you seamlessly manage interactions with your end users based, clearing out inactivate Conversations and staying within the limits of Conversations-per-Participant.

              Ready to build feature-rich Conversations? Check out the following resources:

              Rate this page:

              Need some help?

              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.