Zendesk chat handoff

​

Prerequisites

• A Zendesk account with Admin Center access.
• Your PolyAI project ID (for example PROJECT-f07a975e).
• Your PolyAI messaging handoff base URLs – ask your PolyAI contact for the right values for your environment (dev or prod).

​

1. Create the Conversations Integration in Zendesk

1. In Zendesk Admin Center, go to Apps and integrations > Integrations > Conversations integrations.
2. Click Create integration and name it (e.g. PolyAI Handoff).
3. On the Details tab, record the auto-generated values – you’ll paste them into Studio:

   Field	Purpose
   App ID	Identifies your Zendesk account.
   Integration ID	Identifies this specific integration.
   Webhook ID	Identifies the auto-created webhook.
   Shared secret	PolyAI uses this to verify requests originate from Zendesk.

4. Set the Webhook endpoint to your PolyAI messaging handoff URL. Your PolyAI contact will provide the base domain for your environment. The URL follows this pattern, replacing <BASE_DOMAIN> and <PROJECT_ID>:
   https://<BASE_DOMAIN>/handoff/webhooks/zendesk/PLATFORM/<PROJECT_ID>/live/events
   
5. Set Webhook version to v2.

​

2. Create the Ticket Status Webhook

1. In Admin Center, go to Apps and integrations > Webhooks > Webhooks and click Create webhook > Zendesk events.
2. Configure:

   Setting	Value
   Name	On Ticket Status Changed
   Endpoint	https://<BASE_DOMAIN>/handoff/webhooks/zendesk/PLATFORM/<PROJECT_ID>/live/status (your PolyAI contact will provide the base domain)
   Request method	POST
   Request format	JSON

3. Under Authentication, select API key and use the secret key shared with PolyAI (or generate one and pass it back to your PolyAI contact).
4. On the Event subscription tab, add Status changed.
5. Make sure the webhook shows Active.

​

3. Connect from Studio

• App ID, Integration ID, Webhook ID, Shared secret (from the Conversations Integration).
• Webhook secret key (from the Ticket Status Webhook).
• Zendesk subdomain (the part before .zendesk.com, e.g. d3v-polyai).

​

4. Write the handoff function

def transfer_to_zendesk(conv: Conversation):
    return {
        "utterance": "No problem, I'll transfer you to one of our agents now.",
        "handoff": {
            "text_chat": {
                "zendesk_integration": {}
            }
        }
    }

​

5. Assign the function to a topic

​

6. Verify

• Conversations Integration: Trigger the topic from your widget. Confirm a new conversation appears for the configured Zendesk routing rule. Then reply from Zendesk and confirm the message lands back in the widget.
• Logs: In Zendesk, go to Apps and integrations > Integrations > Logs to see events delivered to the PolyAI endpoint.
• Ticket Status Webhook: Change a ticket’s status in Zendesk and check the webhook’s Activity tab for a successful 200 response.

​

Related pages