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, andtask.note_added. Store the webhook’s secret on your server. - Store
ANSWERING_AGENT_API_KEYandANSWERING_AGENT_WEBHOOK_SECRETas environment variables. - Call
GET /accountwith the integration’s key and storeyou.idasINTEGRATION_USER_ID. The examples use it to recognize notes your integration wrote.
Receive webhook events
Handle every event the same way first:- Verify the
Answering-Agent-Signatureheader against the raw request body. See Verify requests. - Skip the event if you already processed its
id. - Respond with a
2xxstatus within 8 seconds. Do the rest after you respond. - Pass the event to the handler for its type.
Create a ticket from each new task
Thetask.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 withPATCH /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.
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. Theerrorsays why. If your team requires a note to mark a task done, add one withPOST /tasks/{task_id}/notesbefore you send"status": "done".404(not_found) on a task that belongs to a repeat conversation merged into an earlier one has anerrorthat names the task to update instead, such asThis conversation was merged into conversation-184519. Use that task.
Copy task changes to the ticket
Apply status and assignee changes
Atask.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_atof 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
PATCHalso sendstask.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 itsoccurred_at.
Post notes as comments
Atask.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.
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 notask.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.
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, soupdated_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.