Async operations

Some Conversation Orchestrator operations run asynchronously. They return 202 Accepted immediately and complete in the background. This page explains which operations are async, how to poll for completion, and how to extract the resulting resource ID.

Which operations are async?

Async methods	Endpoint
`POST`, `PUT`, `DELETE`	`/v2/ControlPlane/Configurations`
`DELETE`	`/v2/Conversations/{Sid}`
`POST`, `DELETE`	`/v1/ControlPlane/Stores`

All other operations run synchronously and return their results immediately.

Poll for completion

The initial 202 Accepted response contains a statusUrl in the body and a Retry-After header. Send GET requests to the statusUrl until status is COMPLETED or FAILED.

Poll for operation completion

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchOperationStatus() {
14  const operation = await client.conversations.v2
15    .operations("OPERATION_ID")
16    .fetch();
17
18  console.log(operation.operationId);
19}
20
21fetchOperationStatus();

Replace OPERATION_ID with the operation ID from the statusUrl.

A completed memory store operation returns the created resource in result.id:

1{
2  "operationId": "proc_job_01kpttrkrnfjgvwjwcwggqdk96",
3  "status": "COMPLETED",
4  "result": {
5    "id": "mem_store_01kpttrksqe08rhv122gzq52ax",
6    "type": "RESOURCE_ID"
7  }
8}

Status	Meaning	What to do
`PENDING`	Queued or running.	Keep polling.
`COMPLETED`	Finished successfully.	Read `result.id` (or see the following limitation).
`FAILED`	The operation failed.	Inspect the `error` field for details.

If status stays PENDING for more than a few minutes, contact Twilio Support with the operationId.

Known limitation: configuration operations don't return a resource ID

Configuration POST and PUT operations complete with status: COMPLETED but don't populate result.id. To find the configuration ID, list configurations and filter by displayName:

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function listConfiguration() {
14  const configurations = await client.conversations.v2.configurations.list({
15    limit: 20,
16  });
17
18  configurations.forEach((c) => console.log(c.id));
19}
20
21listConfiguration();

Memory store operations populate result.id and don't need this workaround.

Idempotency

Configuration operations accept an Idempotency-Key header so you can safely retry a request without creating a duplicate operation. The key is a UUID that you generate on the client. Generate a new UUID for each request, and reuse the same value only when you're retrying that specific request after a network failure or timeout. Within 24 hours, any retry with the same key returns the original 202 response instead of triggering another operation. Each idempotency key is scoped to your account and region.

Next steps

Quickstart: Create your first configuration.
Troubleshooting: Resolve operation errors and stuck operations.