States and Timers in Conversations

A Conversation can be one of four states:

• active: The conversation is currently in use. This is the default state for a newly created conversation.
• inactive: The conversation is not in use, but you can reactivate it if needed.
• closed: The conversation is no longer in use and you can't reactivate it.
• initializing: Twilio is setting up the conversation and you can't edit it yet. This state is only used shortly when a conversation is created through the ConversationsWithParticipants resource.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateConversation() {
11
  const conversation = await client.conversations.v1
12
    .conversations("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .update({ state: "inactive" });
14

15
  console.log(conversation.accountSid);
16
}
17

18
updateConversation();

1
{
2
  "sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab",
6
  "friendly_name": "friendly_name",
7
  "unique_name": "unique_name",
8
  "attributes": "{ \"topic\": \"feedback\" }",
9
  "date_created": "2015-12-16T22:18:37Z",
10
  "date_updated": "2015-12-16T22:18:38Z",
11
  "state": "inactive",
12
  "timers": {
13
    "date_inactive": "2015-12-16T22:19:38Z",
14
    "date_closed": "2015-12-16T22:28:38Z"
15
  },
16
  "bindings": {},
17
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "links": {
19
    "participants": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",
20
    "messages": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
21
    "webhooks": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks",
22
    "export": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Export"
23
  }
24
}

A conversation can be transitioned between these states by updating the conversation directly, by a configured timer, and automatically by the system. The following table summarizes the possible transitions:

A conversation can be set from active to inactive and vice versa at any time.

As described in the State Transition Table:

• A conversation can only be transitioned to inactive by using a configured timer or by making an API call.
• A conversation is automatically transitioned from inactive to active when a new message is added to the conversation.

Once a conversation closes, it becomes read-only and you can't add new participants or messages to it. Closing a conversation is permanent, and you can't transition it back to the active or inactive state.

Closed conversations don't count towards the Conversations per user limit.

Timers allow you to set a timeframe of inactivity after which a conversation automatically transitions between states. Timers are optional, but we highly recommend enabling them to manage conversations efficiently and avoid distruptions from the Conversations per user limit.

You can set up timers in two ways:

1. Global Defaults: Set up default timers for all conversations created in your account. You can set up global defaults from the Conversations Defaults page in the Twilio Console.
2. For Each Conversation: Set up a timer for a specific Conversation using the REST API.

There are two configurable timers to transition between conversation states:

• Inactive Timer: Transitions a conversation from active to inactive. It counts down from when the last message added was in the conversation.
• Closed Timer: Transitions a conversation to closed.
  • If it's the only timer, it counts down from when the last message was added in the conversation.
  • If there is also an inactive timer, it counts down from when the conversation becomes inactive.

Timers are set in ISO 8601 duration format (PT10M for 10 minutes).

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateConversation() {
11
  const conversation = await client.conversations.v1
12
    .conversations("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .update({
14
      "timers.closed": "PT60000S",
15
      "timers.inactive": "PT5M",
16
    });
17

18
  console.log(conversation.accountSid);
19
}
20

21
updateConversation();

Once set, the timers property of the Conversation resource displays the date and time when the timer will elapse in ISO 8601 date and time in UTC.

1
"timers": {
2
    "date_inactive": "2025-04-16T22:19:38Z",
3
    "date_closed": "2025-04-16TT22:28:38Z"
4
}

When the inactive timer lapses or you manually set the conversation to inactive, the date_inactive property stops returning in the Conversation resources. However, the inactive timer configuration is still retained, and the timer resets if you set the conversation back to active again. To disable a timer entirely, set it to PT0S.

Some other things to be aware of when configuring timers:

• Timers have a precision of 1 second.
• The minimum time for the inactive timer is 60 seconds. For a closed timer, the minimum time is 600 seconds (10 minutes).
• If both timers are set, the closed timer will automatically update based on the inactive timer.
• When a conversation is closed, all timers are removed.