Isolate routing problems by using the contact record (CTR) and contact flow logs
The contact record (CTR) and contact flow logs are the dividing line that tells you whether a routing or contact-handling problem occurred inside Connect Customer (routing configuration and contact flows) or outside it (carrier or device). This is the same approach that audio quality troubleshooting uses when it treats the call recording as the dividing line. This page shows you which fields to read, what to conclude from them, and where to go next.
This reference assumes you are a Connect Customer administrator who can access contact records
(CTRs) and contact flow logs and who can run APIs and CLI commands such as
DescribeContact.
Use this reference as follows:
-
You arrive here from a step in the routing troubleshooting hub or one of its spokes.
-
You read the relevant fields in Section 1 (the CTR) and Section 2 (contact flow logs).
-
You use the dividing-line conclusion table in Section 3 to decide which page to go to next.
-
If a reading doesn't match what you expected, you check the isolation pitfalls in Section 4.
Section 1: Fields to read in the contact record (CTR) with DescribeContact
Call DescribeContact, or review the contact records that you stream to Kinesis, and check the following fields. For the field definitions, see Data model for Connect Customer contact records.
1.1 DisconnectReason
Read this field first to isolate where the disconnect occurred. Each value points in a different direction.
DisconnectReason |
What it indicates | Where to look next |
|---|---|---|
TELECOM_PROBLEM, TELECOM_BUSY,
TELECOM_NUMBER_INVALID,
TELECOM_UNANSWERED, or
TELECOM_TIMEOUT |
A destination or carrier cause on the PSTN side (a third-party network problem, a busy destination, an invalid destination number, an unanswered destination, or a network timeout). You can't resolve these with Connect Customer routing or flow configuration. | Rule out Connect Customer-side configuration first, then confirm coverage and number-type restrictions and open a support case if needed; see Step 5: Delegate boundary issues (carrier, device, audio, or disconnect). |
TELECOM_POTENTIAL_BLOCKING |
Possible spam or reputation blocking by the destination carrier. AWS can't unblock carrier networks for you. | Review your outbound calling practices; see Optimize your reputation for outbound calling in Connect Customer. |
TELECOM_ORIGINATOR_CANCEL |
An originating-side cause. For inbound calls, the caller cancelled before connecting to Connect Customer (often within a second or two). For outbound calls, either the destination didn't answer—in which case Connect Customer sends the cancel after about a 60-second timeout, not a carrier fault—or the agent or API cancelled before connecting. The about-60-second timeout applies only to the outbound-unanswered case. | Check the destination path. For an outbound transfer, review the Transfer to phone number block Timeout; see Flow block in Connect Customer: Transfer to phone number. |
CONTACT_FLOW_DISCONNECT |
The flow ended the contact. | In the flow log, identify the terminal block that the contact reached—a Disconnect block, or an End flow / Resume block in an inbound or disconnect flow—and which branch routed to it. Then see Troubleshoot contact flows that don't behave as expected in Connect Customer. |
CUSTOMER_DISCONNECT |
The caller disconnected. In most cases this isn't a flow or routing problem. | The customer side |
AGENT_DISCONNECT |
For voice contacts, the agent side of the call initiated the
disconnect after the customer and agent were connected. This value
identifies which side disconnected, not why. The Data model for Connect Customer contact records notes that
CUSTOMER_DISCONNECT can't distinguish poor reception
from deliberate disconnection; treat AGENT_DISCONNECT
the same way. |
For uneven distribution or contacts that don't reach an agent, see
Troubleshoot contacts that are not routed, misrouted, or not reaching an agent in Connect Customer. To determine
whether a media or device problem caused the disconnect, check the
DisconnectDetails section of the contact record: a
PotentialDisconnectIssue of AGENT_CONNECTIVITY_ISSUE or
AGENT_DEVICE_ISSUE identifies an agent-side network
or workstation cause. See Troubleshoot call disconnects by using DisconnectDetails in the contact record. Also compare with the
agent activity audit report and the agent's status and activity
state (see the agent audit report pitfall in Section 4: Isolation pitfalls). |
OTHER |
For voice contacts, OTHER covers disconnect reasons
that the preceding codes don't address—for example, a disconnect that
an API call initiates. Chat doesn't use OTHER: a reason
outside its documented list is recorded as null. Chat, task, and
email have a distinct API code. |
Confirm which disconnect reasons apply to the channel in Data model for Connect Customer contact records. Because OTHER doesn't
identify the disconnecting party, isolate from the other fields in
this section (ConnectedToSystemTimestamp, Queue, and Agent) and from
the flow logs in Section 2. |
1.2 ConnectedToSystemTimestamp
-
null—for an outbound, callback, or API contact, the customer endpoint never answered. This often occurs together with aTELECOM_*DisconnectReason, but not always: when the call was never placed at all—for example, an outbound campaign contact that reportsOUTBOUND_ATTEMPT_FAILEDorOUTBOUND_PREVIEW_DISCARDED, or a call blocked by country allowlisting, a quota, or a missing outbound caller ID—this field is alsonull. ReadDisconnectReasonand this field together rather than inferring one from the other, and confirm which reasons apply to the contact type in Data model for Connect Customer contact records. -
A value is present—what this means depends on
InitiationMethod:-
For
OUTBOUND,CALLBACK, andAPI, the customer endpoint answered, so the contact reached Connect Customer. Continue isolating the problem inside Connect Customer (routing or flow). -
For
INBOUND, this timestamp matches the initiation timestamp—the time the contact arrived—so a value being present carries no information about the far end and does not rule out an outside cause.
Check
DisconnectReasonfirst: aTELECOM_*reason points outside Connect Customer even when this timestamp is present. For other initiation methods (for example,TRANSFERorQUEUE_TRANSFER), see Data model for Connect Customer contact records. -
1.3 Queue and Agent
Read these two fields together: Queue is present only if the contact
was queued, and Agent is present only if the contact was connected to an
agent. The combination tells you how far the contact got.
Queue |
Agent |
What it indicates |
|---|---|---|
| Present | Present | The contact was queued and connected to an agent. Compare the queue and agent with the routing target you expected—a different queue points to misrouting (see the Set working queue pitfall in Section 4: Isolation pitfalls and Troubleshoot contact flows that don't behave as expected in Connect Customer). |
| Present | Absent | The contact reached the queue but was never connected to an agent.
Read DisconnectReason before you conclude this is a
routing problem: CUSTOMER_DISCONNECT means the customer
hung up while waiting (an abandoned contact rather than a
misconfiguration; see Data model for Connect Customer contact records). Other
reasons point to routing configuration. |
| Absent | Absent | The contact never reached a queue. Look upstream in the flow—the contact was disconnected, or it never reached a Transfer to queue block. Use the flow logs in Section 2. |
| Absent | Present | The contact wasn't routed through a queue. Check
InitiationMethod: MONITOR produces this
shape (see 1.4 InitiationMethod). |
1.4 InitiationMethod
This field shows how the contact was established. For the flow types associated with each initiation method, see Contact initiation methods and flow types in your Connect Customer contact center.
-
Use it to confirm that a contact for a specific path (for example,
CALLBACK_CUSTOMER_FIRST_QUEUED) was created at all. -
MONITORindicates a monitoring contact, which Connect Customer records separately from the contact that the supervisor monitored. On this contact record:-
The Agent field describes the supervisor, not the agent who handled the customer. StateTransitions confirms this—it records the state transitions of a supervisor, with a state of
SILENT_MONITORorBARGE. -
Queueis null, because the contact wasn't routed through a queue. -
InitialContactIdandPreviousContactIdpoint to the monitored contact, so you can trace back to it.
Use this to isolate reports that the agent field isn't what you expected.
-
1.5 InitialContactId and PreviousContactId
-
InitialContactIdandPreviousContactIdare bothnull—this contact wasn't created from another contact.InitialContactIdnames the first contact in a chain; it isn't set to the contact's own id, so a contact that is itself the first one leaves it empty. To check whether another contact was created from this one—for example, a transfer destination—readNextContactId. Use all three together to isolate duplicate inbound contacts from a single contact that produced a second record. Each genuinely duplicated inbound contact is its own standalone record—bothInitialContactIdandPreviousContactIdarenulland it has noNextContactId—so duplicated inbound contacts each appear as a separate standalone record, distinct from one contact that produced a second record through a transfer. -
PreviousContactIdorNextContactIdhas a value—the contact is part of a chain. Connect Customer sets both fields for the same events: an agent using a quick connect or the CCP number pad, a Transfer to flow, Transfer to queue, or Set disconnect flow block running, or an additional WebRTC participant being added.PreviousContactIdnames the contact this one came from;NextContactIdnames the contact created from this one. -
Follow the chain. For example, a customer first callback spans three contacts: the inbound customer contact (C1), the queued callback contact (C2, with the initiation method
CALLBACK_CUSTOMER_FIRST_QUEUED), and the dialed callback contact (C3, withCALLBACK_CUSTOMER_FIRST_DIALED). Each retry creates another dialed callback contact. See Use customer first callback mode in Connect Customer.
Section 2: Items to read in contact flow logs (CloudWatch)
With contact flow logs enabled, reproduce the problem, and then download the logs for the affected ContactId. For how to retrieve them, see Search flow logs stored in an Amazon CloudWatch log group and Enable Connect Customer flow logs in an Amazon CloudWatch log group.
Read these main items:
-
The block execution order, and the
Resultson the blocks that report one –Success,Timeout,Error, a branch name, or an exception message from the block. Not every block reports aResults; many emit only an entry line with their parameters. Treat a missingResultsas "this block doesn't report one," not as a gap in the log. Identify unexpected branches and the point where the flow ended the contact. A single flow log line can contain both a Parameters object and a Results object; the two are not always on separate lines. -
The QueueId ARN that Set working queue set – routing is determined by the QueueId ARN, not the display name. Compare the ARN in the log with the
describe-queueoutput to confirm it's the intended queue (see also the pitfall in Section 4: Isolation pitfalls). -
The response status of Invoke AWS Lambda function. The Invoke AWS Lambda function block has
SuccessandErrorbranches (and aTimeoutbranch in synchronous mode); it has no default branch. Read the response status in two separate categories rather than as one flat list. A call-level failure—a500, throttling, or a timeout—is retried by Connect Customer (up to three times, up to the configured Timeout) and then takes theErrorbranch. A404or503that the function returns as a value means the invocation itself succeeded, so the block takes theSuccessbranch. These codes are the customer's Lambda function responses, not Connect Customer-defined log fields. Where the contact goes next depends on how the flow author wired the branch. -
The Loop count – a high
LoopCountcan mean a no-input menu repeated until the contact disconnected (CONTACT_FLOW_DISCONNECT), making the call abnormally long.
2.1 When a transferred contact produces no logs
A transfer produces no contact flow logs for the child contact for two different reasons. Confirm which case you are in before you conclude that logging is misconfigured.
-
EXTERNAL_OUTBOUND– a quick connect transfer to an external phone number, or the Transfer to phone number block. No flow type is associated with this initiation method, so the child contact runs no flow and produces no contact flow logs. There is nothing to enable. A missing record here is itself a signal, not a logging misconfiguration. -
TRANSFER– an agent transfer through a CCP quick connect to an agent or queue. This creates a new contact record, and the transfer-destination flow (for example, the agent transfer flow) needs its own Flow block in Connect Customer: Set logging behavior block for the child contact to emit logs. Logging is a per-contact state: within one contact it carries into the queue, whisper, and hold flows, but it does not carry into a separate (child) contact.
2.2 Retrieve all flow logs for a specific ContactId
To retrieve every block log for a specific ContactId without gaps, query CloudWatch Logs Insights with the ContactId as the key. Common reasons that logs aren't found are that Set logging behavior is disabled in the target flow, that logging isn't enabled in the flow for a child contact (the transfer destination), or that you're searching the wrong log group or time range.
What a healthy contact looks like
Before you look for an abnormal reading, know the baseline. The following annotated examples show a normal inbound voice contact that queued and connected to an agent. Values are examples.
Contact record (CTR) – only the relevant fields are shown:
{ "ContactId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "Channel": "VOICE", "InitiationMethod": "INBOUND", "DisconnectReason": "CUSTOMER_DISCONNECT", "ConnectedToSystemTimestamp": "2026-01-15T10:00:03Z", . . "Queue": { "Name": "BasicQueue" }, "Agent": { "Username": "Agent1" }, "InitialContactId": null, "NextContactId": null, "PreviousContactId": null }
In this healthy reading:
-
ConnectedToSystemTimestampis present, so the contact reached Connect Customer. -
QueueandAgentare both present, so the contact was queued and connected to an agent. -
DisconnectReasonisCUSTOMER_DISCONNECT—a normal end (the customer hung up), not a routing fault.
Contact flow log – the Set working queue block logs an entry line that records the QueueId ARN it set:
{ "ContactId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "ContactFlowModuleType": "SetQueue", "Timestamp": "2026-01-15T10:00:05.581Z", "Parameters": { "Queue": "queue-arn" } }
A block that reports an outcome adds a result line. In a healthy flow, the Results value is Success (not Timeout or Error):
{ "Results": "Success", "ContactId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "ContactFlowModuleType": "block-type", "Timestamp": "2026-01-15T10:00:06.012Z" }
Confirm that the Queue ARN matches the queue you intended (see the Set working queue pitfall in Section 4: Isolation pitfalls), that the blocks ran in the order you expect, and that no block reports Timeout or Error. Use this baseline when you compare a successful contact with a failed one. For the full set of contact record fields, see Data model for Connect Customer contact records; for more flow-log examples, see Enable Connect Customer flow logs in an Amazon CloudWatch log group.
Section 3: Dividing-line conclusion table—go from observation to next step
Use the following table to map what you read in Sections 1 and 2 to a destination.
| Observation (CTR or flow log) | Where the problem is | Where to go next |
|---|---|---|
DisconnectReason is TELECOM_PROBLEM,
TELECOM_BUSY, TELECOM_NUMBER_INVALID,
TELECOM_UNANSWERED, TELECOM_TIMEOUT, or
TELECOM_POTENTIAL_BLOCKING, or
ConnectedToSystemTimestamp is null for a contact that
was dialed but not answered—a queued callback that was never dialed also
has a null value (see Section 1.2) |
Destination or carrier (outside Connect Customer); for
TELECOM_POTENTIAL_BLOCKING, carrier spam or reputation
blocking |
Rule out Connect Customer-side configuration first, then confirm coverage and number-type restrictions and open a support case if needed; see Step 5: Delegate boundary issues (carrier, device, audio, or disconnect). For spam or reputation blocking, see Optimize your reputation for outbound calling in Connect Customer. |
DisconnectReason is
TELECOM_ORIGINATOR_CANCEL |
Originating side. For inbound calls, the caller cancelled before connecting to Connect Customer (often within a second or two). For outbound calls, the destination didn't answer (Connect Customer sends the cancel after about a 60-second timeout, which applies only to this outbound-unanswered case), or the agent or API cancelled before connecting | Check the destination path. For an outbound transfer, review the Transfer to phone number block Timeout; see Flow block in Connect Customer: Transfer to phone number. |
After porting, inbound calls flow into the contact flow of a different
number (the number the customer dialed and the contact record's
SystemEndpoint.Address—shown as System address or number
in contact search—don't match) |
Carrier number mapping | See How to port your numbers to Connect Customer. |
The contact enters the queue but isn't distributed to an agent, and
DisconnectReason isn't
CUSTOMER_DISCONNECT |
Routing configuration (routing profile association or concurrency) or the agent's status (Available, Offline, or a custom status). | Troubleshoot contacts that are not routed, misrouted, or not reaching an agent in Connect Customer |
The contact never reached a queue (Queue is
absent) |
The flow—the contact was disconnected, or never reached a Transfer to queue block | Troubleshoot contact flows that don't behave as expected in Connect Customer |
DisconnectReason=CONTACT_FLOW_DISCONNECT, an unexpected
branch, or a wrong QueueId ARN |
Contact flow (block behavior, branching, Set working queue, or a dependent Lambda) | Troubleshoot contact flows that don't behave as expected in Connect Customer |
| Invoke Lambda returns an error or an unexpected value, and the Error or No Match branch isn't wired to the intended queue | The flow (Lambda integration and the Error / No Match branch wiring) | Troubleshoot contact flows that don't behave as expected in Connect Customer |
| The problem occurs across multiple queues or sites at once, with no customer-side change | An AWS service event or a Regional service issue | Check the AWS Health Dashboard |
Section 4: Isolation pitfalls
These are points that are easy to misread. When a reading doesn't match what you expected, check here first.
- 4.1 The draft isn't the same as the published version (unpublished changes)
-
The visual editor shows the draft; the contact runs the published version. These can differ when a draft change (for example, a Set working queue change) was never published. For a flow that has been published, DescribeContactFlow returns the published version by default, and returns the draft when you pass the
:$SAVEDalias. Retrieve both and compare them to find unpublished changes; if they differ, republish from the UI. The flowStatusfield (PUBLISHEDversusSAVED) does not indicate whether there are unpublished draft changes—a flow can bePUBLISHEDyet still have a newer draft. AStatusofSAVEDmeans that the flow has never been published. - 4.2 Set working queue is determined by the QueueId ARN, not the display name (out-of-UI edits can leave the display name stale)
-
When you update a flow through the UpdateContactFlowContent API or an import, the QueueId ARN can be replaced while the display name in the UI stays the same. The UI looks correct, but the contact is misrouted to a different queue. Compare the ARN in the exported JSON with
describe-queue. To fix a stale queue reference, open the block and re-select the queue, and then save and publish. - 4.3 Detect out-of-UI edits (CloudTrail
UpdateContactFlowContent) -
When behavior changed on a specific date after previously working, check CloudTrail for UpdateContactFlowContent calls. A UI edit is recorded with
invokedBy=connect.amazonaws.comand a principal that is the service-linked roleAWSServiceRoleForAmazonConnect(itsuserAgentis alsoconnect.amazonaws.com). An event with noinvokedByis a direct out-of-UI call (API, import, CI/CD, CloudFormation, or Lambda), and itsuserIdentity.typecan be eitherIAMUserorAssumedRole. Note the exception: events from the service-linked roleAWSServiceRoleForAmazonConnectSynchronizationare Connect Customer managed cross-Region synchronization, not a UI edit. - 4.4 A transfer from an upstream carrier or PBX doesn't create a CTR until it reaches a phone number claimed in your Connect Customer instance
-
A call transferred from an upstream carrier or PBX creates a
SearchContactsentry and a CTR only after it reaches a phone number claimed in your Connect Customer instance. A call that fails before that point leaves no record in Connect Customer. Interpret "no record" as possibly meaning "the call failed before it reached Connect Customer." - 4.5 The agent audit report status and the 20-second no-answer timeout
-
The Agent Activity Audit report distinguishes Agent Disconnected, Contact Missed, and Rejected. For voice, a contact that isn't answered and a contact that is rejected are both recorded as Agent Disconnected. For chat, both are recorded as Contact Missed. For task and email, a contact that isn't answered is recorded as Contact Missed, and a rejected contact is recorded as Rejected. For details, see When is the status Agent Disconnected, Contact Missed, or Rejected?. The time an available agent has to answer before the contact is counted as not answered is 20 seconds for voice or chat, and 30 seconds for a task. This ring time is fixed and can't be configured. A contact that isn't answered is routed to the next available agent.
Because the audit report records both a no-answer and a reject as Agent Disconnected for voice (and both as Contact Missed for chat), the audit report status alone can't separate a missed contact from a rejected one on those channels. To distinguish them, use the Contact State in the agent event stream, where
MISSEDandREJECTEDare separate states (REJECTEDalso covers a customer who abandoned the contact while it was connecting to the agent); the audit report is a report version of the same data. Read the CTRDisconnectReasontogether with these signals.
Related topics
-
Hub: Troubleshoot contact routing and handling in Connect Customer
-
Spoke: Troubleshoot contacts that are not routed, misrouted, or not reaching an agent in Connect Customer
-
Spoke: Troubleshoot contact flows that don't behave as expected in Connect Customer
-
Search flow logs stored in an Amazon CloudWatch log group, Enable Connect Customer flow logs in an Amazon CloudWatch log group, and Flow block in Connect Customer: Set logging behavior