Common issues
| Symptom | Likely cause | Fix |
|---|---|---|
| Test & Connect fails | Invalid App Key or User Key; User Key currency does not match any affiliated company; sandbox mode toggled incorrectly | Double-check both keys in FareHarbor’s partner portal. Confirm the User Key currency matches the company you expect. If testing, make sure sandbox mode is on. |
| AI does not offer booking options | FareHarbor not connected; all actions disabled; no items returned for the configured company | Verify the integration is connected in Settings → Add-ons. Check that at least List Tours and Check Availability are enabled. Confirm the default company has published bookable items in FareHarbor. |
| No availability returned for a date | No open slots on that date; the company has no availability configured for the selected item; date format mismatch | Check the FareHarbor dashboard for the company’s availability calendar. The AI sends dates in YYYY-MM-DD format — verify the item actually has slots published for the requested date. |
| AI asks the customer which location when it shouldn’t have to | Connection names are too generic (e.g. “Account 1”, “Test”); customer’s request doesn’t clearly map to a connection | Rename each connection to something customers would recognize (a brand, region, or company name). Set a default_company_shortname so the AI can match tour and company mentions to the right connection. |
| Payment link SMS not delivered | Customer phone number not in international format; SMS delivery failure | The phone number must include the country code (e.g. +1 for US, +64 for NZ). Verify the number is correct and reachable. If the number is correct but SMS still fails, contact support. |
| None of the above | — | Contact OpenCX support with your organization name and a description of the issue. Include the session ID from the inbox if available. |
Most connection issues come from mismatched keys or currency. If Test & Connect fails, the error message from FareHarbor’s API is shown in the dashboard — read it carefully before retrying.
Booking-specific issues
If the AI connects and lists tours but bookings fail or behave unexpectedly, check these items:- Create Booking is disabled by default. The AI cannot confirm reservations unless you explicitly enable the Create Booking action in FareHarbor settings. This is intentional — most teams use payment links instead.
- Cancellation has a grace period. FareHarbor allows cancellations only within a short window after creation. The AI checks
is_eligible_for_cancellationbefore attempting to cancel. If the grace period has passed, the booking cannot be cancelled through the AI. - Always validate before creating. The AI validates availability and pricing before every booking attempt, but if the time slot fills between validation and creation, the booking will fail. The AI handles this by informing the customer and asking them to pick a different slot.
- Sandbox bookings are not real. When sandbox mode is on, all bookings are created in FareHarbor’s demo environment. They will not appear in your production FareHarbor dashboard and no confirmation emails are sent to real addresses.
Limits
| Limit | Value |
|---|---|
| Connections per organization | Unlimited (one per location/brand/currency) |
| Connection name | Unique within the organization |
| Default company per connection | 1 (or Auto-detect) |
| AI actions | 8 toggleable actions, per connection |
| Payment link SMS | Requires international phone format |
Related Documentation
Connect FareHarbor
Re-verify your keys and sandbox setting.
Booking Flow
How each AI action works day-to-day.
Overview
Capabilities and supported channels.
Voice
SMS payment link delivery during voice calls.