Troubleshooting

To investigate a Conversation Orchestrator problem after the fact, you can use the Twilio Debugger. The Debugger shows info, warning, and error events for conversations, participants, communications, and profile resolution on your account. Open it from Develop > Troubleshoot > Debugger in the Twilio Console, or from the Debugger tab in the Twilio Workbench. The Debugger is available in the US1 region only.

Filter by source conversation-orchestrator to see only Conversation Orchestrator events. The following event types are available:

Diagnostic events have a Twilio error code. Look up any code in the Error and Warning Dictionary. Conversation Orchestrator codes are in the 530xxx range. To trace one request end to end, match the requestId or correlationId on each event to the Twilio request ID returned on API responses and set on outbound webhook headers.

All Conversation Orchestrator errors follow this format:

1
{
2
  "code": 20003,
3
  "httpStatusCode": 401,
4
  "message": "Terms of service have not been accepted.",
5
  "userError": true,
6
  "params": { "field": "termsOfService", "value": "not_accepted" }
7
}

If you send an SMS or make a call but no conversation appears, check these in order:

1. Check that capture rules match. Fetch your configuration and inspect channelSettings.CHANNEL_NAME.captureRules. Make sure your capture rules are bidirectional: one with your Twilio address as from, one as to.
2. Verify E.164 phone number format. Capture rules compare addresses exactly, so your Twilio number must include the + and country code.
3. Allow for propagation. After creating or updating a configuration, wait 5-10 seconds before sending test traffic.
4. Check for overlapping capture rules across configurations. If multiple configurations match the same address, Conversation Orchestrator doesn't guarantee which one handles the traffic.

If the conversation exists but doesn't appear in the default list, search by the original Twilio Message or Call SID using the channelId query parameter on the Conversations endpoint.

Conversation Orchestrator creates voice communications from real-time transcription, not from the call itself. This means a communication is only created when someone speaks and that speech is transcribed. If the call is silent or transcription isn't running, no communications appear. To test, make sure someone speaks during the call and confirm that your voice capture rules are set up correctly.

The timeout clock for voice only starts when a transcription event is received. A silent call produces no transcription, so the conversation never transitions out of ACTIVE.

You can resolve this in one of the following ways:

• Set "statusTimeouts": null on the VOICE channel so conversations close as soon as the final transcription event arrives.
• Close stuck conversations manually. See Close conversations with the API.

For the underlying architecture, see Voice timeouts behave differently.

Some API requests run asynchronously and can fail or stall. For background on how these requests work, see Asynchronous operations.

• Stuck in PENDING. Wait at least 30 seconds. If the operation is still PENDING, contact Twilio Support with the operationId, timestamp, and Account SID.
• Fails immediately. Inspect the error message in the operation response. Common causes are invalid phone numbers, a missing or invalid memoryStoreId, and malformed capture rules.
• Completed but no resource ID. This is a known limitation for configuration POST and PUT operations. For the workaround, see Asynchronous operations.

Only CUSTOMER participants get profiles. Profile resolution is best-effort and asynchronous, so briefly null values are normal. Check:

1. The participant's type is CUSTOMER.
2. The configuration has a memoryStoreId set.
3. The address matches the profile trait format exactly (E.164 with + for phone, and so on).
4. The participant was created through active ingestion. In passive ingestion, profiles aren't created automatically; the type must be explicit. See Profiles.

If memory extraction is on but no observations appear on the profile, check the following in order:

1. Verify that memoryExtractionEnabled is true. Fetch the configuration and inspect the field.
2. Verify that the memory store is in the ACTIVE state. Send a GET request to /v1/Stores/{storeId} and check status.
3. Verify that the memoryStoreId is correct. Cross-reference the store ID in the configuration with the actual store.
4. Confirm that the conversation reached the extraction trigger state. Fetch the conversation and check its status. If the conversation is still ACTIVE, extraction hasn't fired yet.
5. Verify that the CUSTOMER participant has a profileId. If profileId is null, profile resolution failed and extraction has no target profile.

For issues with what gets extracted (not whether extraction fires), see Conversation Memory.

1. Verify intelligenceConfigurationIds is present on the configuration. Fetch the configuration and inspect the field. A prior PUT request that omitted this field would have deleted it. See Updating a configuration.
2. Check whether the configuration was updated after the conversation was created. Conversations pin the configuration version at creation. New intelligence configurations only apply to new conversations.
3. Verify the operator is configured for the correct trigger. The COMMUNICATION trigger fires once per communication. The CONVERSATION_END trigger fires on CLOSED. Verify you're waiting for the right lifecycle event.

If conversations from different customers land in the same conversation, check the following causes:

Passive voice capture rules default to PSTN matching. To capture CLIENT and PUBLIC_SIP calls, include explicit callType metadata in the rule.

A rule without callType doesn't capture CLIENT calls:

{ "from": "*", "to": "+15551234567" }

A rule that captures CLIENT calls:

{ "from": "*", "to": "agent-1", "metadata": { "callType": "CLIENT" } }

A rule that captures SIP calls:

{ "from": "*", "to": "+15551234567", "metadata": { "callType": "PUBLIC_SIP" } }

To troubleshoot this problem, take the following steps:

1. Verify that the callType metadata is present on the capture rule.
2. Verify that the to address matches the actual address format for that call type.
3. For CLIENT calls with dynamic identities, switch to active TwiML ingestion instead of passive capture rules.

Conversation Relay writes one communication per text-to-speech (TTS) fragment, not one communication per complete agent response. A single agent utterance might produce three to five communications depending on how the TTS engine chunks the text.

This behavior has three effects:

• Communication lists are longer than expected (3-5x for agent turns).
• Intelligence operators with the COMMUNICATION trigger fire once per fragment, which multiplies operator cost.
• Webhook handlers (statusCallbacks) receive more events than anticipated.

If you need per-turn analysis, use the CONVERSATION_END trigger on intelligence operators instead of the COMMUNICATION trigger.

• Asynchronous operations: Polling, idempotency, and SDK examples.
• Core concepts: The object model.
• Profiles: How participant types and profiles resolve.
• Conversation lifecycle: Timeouts, voice behavior, manual close.