Conversations API (v2) - Operation endpoints

(information)

Legal information

Conversation Orchestrator, including the APIs, may use artificial intelligence or machine learning technologies and is subject to the terms of the Predictive and Generative AI/ML Features Addendum. For details on AI usage and data, see the AI Nutrition Facts for Real-Time Transcription and Conversation Relay.

Conversation Orchestrator is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

Overview

Poll the status of a long-running operation.

Endpoints

GET

/v2/ControlPlane/Operations/{Sid}

Get Operation Status

GET/v2/ControlPlane/Operations/{Sid}

Base url: https://conversations.twilio.com (base url)

Retrieve the current status of a long-running operation. Operations progress through: PENDING -> RUNNING -> COMPLETED or FAILED.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

Not PII

Responses

200400404429500503

Operation status

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

operationIdstring

Optional

Not PII

Unique identifier for the long-running operation.

Example: proc_job_01h9d8r0vte3hz8tykdj329t7r

statusenum<string>

Optional

Not PII

Current status of the operation.

Example: COMPLETEDPossible values:

PENDINGRUNNINGCANCELLEDCOMPLETEDFAILED

createdAtstring<date-time>

Optional

Not PII

Timestamp when the operation was created.

Example: 2025-01-15T10:30:00Z

completedAtstring<date-time>

Optional

Not PII

Timestamp when the operation completed. Only present for completed or failed operations.

Example: 2025-01-15T10:30:05Z

statusUrlstring<uri>

Optional

Not PII

URL to poll for operation status.

Example: https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r

errorobject

Optional

Not PII

Error details if the operation failed. Follows RFC 9457 Problem Details.

Show error properties

relatedobject

Optional

Not PII

Named resource identifiers associated with this operation. Keys depend on the operation type:

config-create, config-update, config-delete: configurationId
conversation-delete: conversationId

Example: {"configurationId":"cfg_configuration_01h9d8r0vte3hz8tykdj329t7r"}

Show related properties

Get Operation Status

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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchOperationStatus() {
11  const operation = await client.conversations.v2.operations("Sid").fetch();
12
13  console.log(operation.operationId);
14}
15
16fetchOperationStatus();

Response

1{
2  "completedAt": "2009-07-06T20:30:00Z",
3  "createdAt": "2009-07-06T20:30:00Z",
4  "error": {
5    "type": "https://www.example.com",
6    "title": "title",
7    "status": 400,
8    "detail": "detail",
9    "instance": "https://www.example.com"
10  },
11  "operationId": "operationId",
12  "related": {},
13  "status": "COMPLETED",
14  "statusUrl": "https://www.example.com"
15}