> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Front troubleshooting

> Debug Front connection, webhook, handoff, and sync issues — 401 credential failures, missing AI replies, duplicate messages, broken escalations.

Before debugging, have this ready:

* Your Front <Tooltip tip="The API token generated in Front's Developer Settings. Used to authenticate API calls between OpenCX and your Front workspace.">API token</Tooltip> and the <Tooltip tip="The Front teammate account the AI posts replies as.">AI teammate</Tooltip> you selected.
* A specific <Tooltip tip="OpenCX's identifier for a single conversation thread. Visible in the Inbox URL.">session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Front conversation ID where the problem shows.
* The webhook URL shown in [Settings → Ticketing System](https://platform.open.cx/settings/ticketing) → Front.

<Tip>
  Re-enter your credentials in [Settings → Ticketing System](https://platform.open.cx/settings/ticketing) → Front as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** find the conversation in your [OpenCX Inbox](https://platform.open.cx/inbox) and check the session's AI reasoning, tool calls, and handoff event. That's far faster than inspecting webhooks or logs.
</Info>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Invalid Front API token" on save**

<Tooltip tip="Usually caused by a revoked or expired token, or a Front plan without API access.">Likely cause</Tooltip>: token revoked, expired, or plan doesn't include API access.

**Fix:** regenerate the API token in Front's [Developer Settings](https://app.frontapp.com/settings/developers/tokens). Confirm the token has the required scopes (Shared Resources, Private Resources, Provisioning). Confirm your Front plan includes API access.

### **Webhook not receiving events**

<Tooltip tip="The webhook URL was not configured in Front, or the event subscriptions are incomplete. Without the webhook, OpenCX receives no conversation events.">Likely cause</Tooltip>: webhook URL not configured in Front, or wrong event subscriptions.

**Fix:** open your Front app's webhook settings and confirm the webhook URL matches the one shown in [Settings → Ticketing System](https://platform.open.cx/settings/ticketing) → Front. Confirm the webhook is receiving inbound, outbound, and conversation archived events at minimum.

### **AI not responding to conversations**

<Tooltip tip="The conversation may not be assigned to the AI teammate, or the integration may be disabled. OpenCX only processes conversations assigned to the selected teammate (or unassigned, if that option is enabled).">Likely cause</Tooltip>: conversation not assigned to AI teammate, integration disabled, or **Handle unassigned** is off.

**Fix:** check these in order:

1. Confirm the conversation is assigned to the teammate you selected as the AI teammate in [settings](/integrations/front/connect#settings-reference).
2. If the conversation is unassigned, confirm **Handle unassigned conversations** is enabled.
3. Confirm the integration is enabled (the master toggle is on).
4. Confirm the message is from a customer, not a teammate — the AI skips teammate-initiated and outbound messages.

### **Handoff posts a note but conversation stays assigned**

<Tooltip tip="The unassign API call may have failed or a concurrent Front rule reassigned the conversation before the unassign completed.">Likely cause</Tooltip>: API error during unassign, or a concurrent Front rule reassigned the conversation.

**Fix:** this is usually transient. If it happens consistently, check whether a Front rule or automation is reassigning the conversation immediately after OpenCX unassigns it. Review the session in your [OpenCX Inbox](https://platform.open.cx/inbox) for error details.

### **Duplicate AI replies on the same message**

<Tooltip tip="The deduplication hash expired (24-hour TTL) or concurrent webhook deliveries arrived before the first was fully processed.">Likely cause</Tooltip>: dedup window expired or concurrent webhook retries.

**Fix:** OpenCX deduplicates messages by content hash with a 24-hour window. If Front retries a webhook delivery after the window expires, a duplicate can occur. This is rare — if it happens consistently, confirm your Front webhook is not configured to retry aggressively.

### **AI archived a conversation that a rep was working on**

<Tooltip tip="The AI only archives conversations assigned to the AI teammate. If the conversation was reassigned to a rep but the resolve event was already in flight, a race condition may have occurred.">Likely cause</Tooltip>: timing overlap between reassignment and AI resolution.

**Fix:** OpenCX checks the conversation assignee before archiving. If the conversation is no longer assigned to the AI teammate, the archive step is skipped. If this happened, the conversation can be reopened in Front. If it recurs, review your routing rules for timing conflicts.

### **Knowledge Sync not importing articles**

<Tooltip tip="The API key may lack read permissions, the Help Center selection may be empty, or the sync hasn't been started.">Likely cause</Tooltip>: wrong API key, no Help Centers selected, or sync not started.

**Fix:** check these in order:

1. Go to [**Data Sources**](https://platform.open.cx/data-sources) and confirm the Front source shows a recent sync time.
2. Confirm the API key has read access to Help Center content.
3. Confirm at least one Help Center is selected.
4. Click **Sync now** to trigger a manual sync.

### **None of the above**

If your issue doesn't match any scenario above, gather the session ID from your [OpenCX Inbox](https://platform.open.cx/inbox) and the Front conversation ID, then contact support.

## Limits and timing

|                                  | Value                                 |
| -------------------------------- | ------------------------------------- |
| **Message deduplication window** | 24 hours                              |
| **Webhook event processing**     | Real-time (on delivery)               |
| **AI teammate selection**        | One per organization                  |
| **Teammate replies**             | Skipped (not processed by AI)         |
| **Archive on resolve**           | Only if AI teammate is still assigned |

<Note>
  OpenCX retries on transient Front API failures but does not indefinitely retry. If your Front workspace is rate-limited or experiencing downtime, some webhook events may be missed. Check your Front webhook delivery logs for failed deliveries.
</Note>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    Re-verify credentials and webhook setup.
  </Card>

  <Card title="Conversations" icon="messages" href="/integrations/front/conversations">
    How messages flow and how handoff works.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/front/channels/email">
    Per-channel details for Email, Chat, SMS, and Phone.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>