Skip to main content
This guide connects Answering Agent tasks to a ticket system such as ClickUp or Zendesk. The webhook creates each ticket and copies task changes and notes to it. PATCH /tasks/{task_id} writes ticket changes back. A job that calls GET /tasks with updated_since catches new tasks and status and assignee changes the webhook missed. It cannot recover a missed note.

Before you start

  • Create a dedicated login for the integration, such as integrations@yourcompany.com, on one team with the admin role. Create the API key from that login. See Authenticate.
  • Set up the webhook. Under Events, check task.created, task.updated, and task.note_added. Store the webhook’s secret on your server.
  • Store ANSWERING_AGENT_API_KEY and ANSWERING_AGENT_WEBHOOK_SECRET as environment variables.
  • Call GET /account with the integration’s key and store you.id as INTEGRATION_USER_ID. The examples use it to recognize notes your integration wrote.
The examples use this helper:

Receive webhook events

Handle every event the same way first:
  1. Verify the Answering-Agent-Signature header against the raw request body. See Verify requests.
  2. Skip the event if you already processed its id.
  3. Respond with a 2xx status within 8 seconds. Do the rest after you respond.
  4. Pass the event to the handler for its type.

Create a ticket from each new task

The task.created event carries the task in data, the same object GET /tasks/{task_id} returns. It has the title, description, status, assignee, category, priority, customer, and source. Create the ticket from data, and store data.id, the API task ID, on the ticket.
createTicket stands for your ticket system’s own client. Store the task’s id, and store its status, assignee?.id, and updated_at as the last synced values.

Write ticket changes back

When someone changes a ticket’s status or assignee, send the change with PATCH /tasks/{task_id}. The values you read are the values you send. status is open, in_progress, on_hold, or done. assigned_to takes the same ID as a task’s assignee.id. Map these to your ticket system’s statuses and users in your own config. GET /account lists up to 50 members with their id and name. Set expected_status to the status your sync last saw. If someone changed the task in the dashboard since then, the API returns 409 and changes nothing. Always send assigned_to with a status change. Without it, in_progress, on_hold, and done can assign the task to the integration login, the same as a click in the dashboard.
The task’s activity shows each change as made by the integration login. Your PATCH also sends a task.updated event, and the next section shows how to skip it. To copy a ticket comment to the task, send it to POST /tasks/{task_id}/notes as content. Only your team sees the note. Each request adds a note, so send each comment once. Skip comments that your integration posted from a task note. Otherwise each of those notes comes back to the task a second time. Tasks from forms do not take notes. Other errors to handle:
  • 422 (unprocessable) means the dashboard would refuse the same change. The error says why. If your team requires a note to mark a task done, add one with POST /tasks/{task_id}/notes before you send "status": "done".
  • 404 (not_found) on a task that belongs to a repeat conversation merged into an earlier one has an error that names the task to update instead, such as This conversation was merged into conversation-184519. Use that task.

Copy task changes to the ticket

Apply status and assignee changes

A task.updated event arrives when a task’s status or assignee changes, from the dashboard, the API, the MCP server, or the AI. changes holds only the values that changed. Map changes.status.to and changes.assignee.to to your ticket system’s statuses and users with the same config you use to write back. changes.assignee.to is null when nobody is assigned. It is also null when the new assignee’s account was deleted or has no name. GET /tasks/{task_id} shows that task with assignee: null too, so clear the ticket’s assignee in both cases. Two checks keep the ticket correct:
  • Events can arrive out of order. Store the occurred_at of the newest event for each task, including events you skip. Never apply an event older than that. Read the task again and copy its current state instead, so a late event cannot roll the ticket back.
  • Your own PATCH also sends task.updated. If the new values equal the last synced values you stored, the change came from your integration, and the ticket already has it. Skip the event, but still store its occurred_at.

Post notes as comments

A task.note_added event arrives when someone adds an internal note to a conversation task. Post note.content to the ticket as a comment. Skip notes your integration wrote. Those notes came from ticket comments, and their note.author.id is the integration login’s ID.
Mark each comment you post this way as one from your integration, so the step in Write ticket changes back does not send it back as a note.

Poll for changes

The webhook events keep tickets current. The poll catches status and assignee changes they miss. Answering Agent drops an event after its last retry fails, and it sends nothing while the webhook address is cleared. A few automatic changes also send no task.updated today: a transferred call that reopens a task, the AI clearing an assignee nobody claimed, and automatic assignment after the AI reviews a text conversation. The poll cannot recover a note, because the API does not return notes. A dropped task.note_added never reaches the ticket. Run the poll every 15 minutes to an hour. Each run asks for the tasks that changed since the last run with GET /tasks?updated_since=<cursor>&limit=50. Leave out status, so tasks that moved to done come back too. Update the ticket for each task, or create the ticket if you don’t have one. Search results leave out description, so read the full task with GET /tasks/{task_id} only when you create a ticket. Then move the cursor. The cursor is the last updated_at you processed. Store it between runs, and save a starting value before the first run, such as the time you turn the sync on. updated_at is in whole seconds, and several tasks can share one. Answering Agent can also save a change with a time a little earlier than when the change shows up in search, for example when a save takes a moment to commit. So start each run a few minutes before the stored cursor, and update a ticket only when the task’s status or assignee differs from what the ticket last synced.
Results come oldest change first, so the cursor only moves forward. A task that changes while you page moves to the end with a newer updated_at, and the next run still sees it. Reading a task twice is harmless, because the job only creates a missing ticket or updates an existing one. After each page, the job asks for page 1 again from the last updated_at on that page. When a full page shares one updated_at, that request would return the same page, so the job reads the next page instead. In the rare case that more than 50 tasks share one second and one of them changes mid-run, a tied task can be skipped. The cleanup below reads every open ticket’s task and fixes that.

Clean up deleted and merged tasks

A task that is deleted or merged into another task drops out of the results instead of coming back, so updated_since can’t tell you it is gone. Once a night or once a week, check each ticket that is still open on your side. The same pass also refreshes each open ticket from its task. GET /tasks/{task_id} returns 404 for a task that is gone. For a merged task, the error names the task to use instead, such as This conversation was merged into conversation-184519. Use that task.
findTicket, updateTicketFromTask, updateTicketFields, addTicketComment, saveTicket, openTickets, and closeTicket stand for your ticket system’s own client. loadCursor and saveCursor stand for your own storage. updateTicketFromTask copies the task’s status and assignee to the ticket and stores them as the last synced values. A poll costs one request for each page of changed tasks, plus one for each ticket it creates. The cleanup costs one request for each open ticket. The API allows 120 requests per minute for each person, so a cleanup of 600 open tickets takes at least 5 minutes. The helper above waits and retries on 429.