Overview
Triage Agent is good at troubleshooting and gathering information. It can take what it collected and either hand it to a technician or kick off an automation, by POSTing the collected fields to a URL of your choosing. That URL can be a Robotic Process Automation platform such as Rewst, Microsoft Power Automate or Logic Apps, Azure Functions, Zapier, Make, or anything else that accepts a webhook. Common uses:- Triggering a user onboarding or offboarding
- Looking up a help article in IT Glue or Hudu and sending it to the end user
- Assigning a license in Microsoft 365
- Resetting a password and returning a one-time link
Configure the Automation URL
The Automation section lives on an intent variation in Thread Admin → Magic Agents → Catalog, alongside the variation’s arguments (the form fields Triage Agent collects from the customer).
URL requirements
The URL you save is not validated, so a malformed one is accepted and fails silently at run time. Check these yourself:- Include the scheme.
https://hooks.example.com/onboardworks,hooks.example.com/onboarddoes not. - Query strings are preserved, so
?code=abc123style Power Automate and Azure Function URLs work as-is. - Credentials in the URL are stripped.
https://user:pass@host/pathis rebuilt ashttps://host/path, so URL-embedded basic auth silently loses its credentials. Use a header instead. - Fragments are dropped.
Authenticating the request
Thread does not sign the request body, so there is no HMAC signature for your endpoint to verify. Authenticate with a shared secret in a header and treat that header as the only proof the call came from Thread.Headers are static key/value pairs. Thread does not substitute variables (such as intent fields or ticket data) into header values. All dynamic data about the request arrives in the JSON body via
intent_fields and meta_data.How it works
- Triage Agent detects the intent from the customer’s message.
- It asks the customer for the variation’s arguments and confirms the answers back to them.
- If the variation has an approval configured, the request goes to the approver first. The automation fires only once the approval is granted, and never fires if it is rejected or left pending.
- Thread POSTs to your Automation URL and waits for your response before replying to the customer.
- It relays your
messageto the customer and writes yourinternal_messageto the ticket as an internal note.
Intents also fire on tickets created by a Voice AI call, and those hit the same Automation URL with the same contract. Design your endpoint to be indifferent to which channel the ticket came from.
Request payload
Thread sends a POST with the following JSON body.intent_fields
These are dynamic, built from the arguments (form fields) you created on the variation, and the value is what the customer submitted.- Argument names are converted to snake_case. An argument named “Group Email” arrives as
group_emailand “User Name” arrives asuser_name. - Every declared argument is always present. An argument the customer did not answer arrives as an empty string, not
nulland not an absent key. Test withfield == ""rather than a null or existence check, or an optional field will look answered. - Fields follow the argument order you set on the variation.
meta_data
meta_data describes the ticket and requester. ticket_id is the ticket number in your PSA, while thread_id is Thread’s own internal identifier for the conversation. Unlike intent_fields, keys here are omitted when the underlying record is absent, so treat everything except ticket_id and thread_id as optional.
Use
company_id to scope the runbook to the right tenant. It is the client’s id in your PSA, so it maps cleanly onto a Rewst organization variable or a Power Automate tenant lookup.
Response
Return a 2xx status with a JSON body. The fields Thread reads:error.messagewins overmessage. If your body contains anerrorobject with amessageinside, Thread relays that string instead, on success responses as well as failures. Do not send anerrorobject on a success.- A non-2xx response is still read. Thread parses the body and relays
error.messageormessage, so you can return a useful explanation with a4xxand the customer gets a sensible reply. - An empty or unparseable success body falls back to a generic confirmation, “Was executed successfully”. An unparseable error body falls back to “Error while executing automation”.
- Configured replies win over
message. If the variation has admin-configured replies, those are sent instead of yourmessage. Leave replies empty when you want your runbook to own the wording.
Multi-step automations
A single question-and-answer round is rarely enough for a real runbook. An onboarding request needs a manager who exists in Microsoft 365, a license that is actually available, and a mailbox address that is not already taken. Your automation cannot know any of that until it looks, and by then Triage Agent has already stopped asking.status: "continue" closes that gap. Your automation answers with “not yet, ask them this”, Triage Agent goes back to the customer in its own words, and your runbook gets called again with the answer. This is the mechanism behind validation loops: an invalid email address, an ambiguous user match, a missing manager, a choice between license tiers.
The continuation loop
Each round trip works like this:- Your endpoint returns
status: "continue"with acontinuation_tokenand aform. - Thread stores the in-progress step against the ticket, intent and variation, together with every field value collected so far.
- Triage Agent is prompted to ask the customer for the new fields. It phrases the question itself, so your
messageis context for the agent rather than a script it reads out. - When the customer answers, the intent’s collection schema is temporarily replaced by your
formfields, so the agent asks for exactly those and nothing else. - Thread POSTs again to the same URL with the accumulated
intent_fields(everything from every step, later answers overwriting earlier ones under the same key) pluscontinuation_tokenat the top level. - Repeat until your endpoint returns
complete.
Continue response format
continuation_token is opaque to Thread. It is stored and echoed back verbatim, so use it to carry whatever your platform needs to resume: a Rewst workflow instance id, a Power Automate run id, or a key into your own state store.
Example: re-asking for a valid email address
An onboarding intent collects a new hire’s name and their manager’s email. Rewst looks the manager up in Microsoft 365 and finds nothing. Step 1, Thread to Rewst. The customer typed the manager’s address with a typo.start_date. It is an optional argument on the variation that the customer never answered, so it arrives as an empty string rather than being absent.
Step 1 response, Rewst to Thread. The lookup failed, so the workflow parks itself and asks again.
message as context for why. Nothing about “step 1” or the token is visible to the customer.
Step 2, Thread to Rewst. employee_name and the empty start_date are carried forward, and manager_email is overwritten with the corrected value.
manager_email until it resolves, re-ask mailbox_alias until it is free, or send back a multiple field when a lookup returns several matching users and the customer has to pick one.
Limits and edge cases
- Ten round trips maximum. A
continuebeyond the tenth step ends the exchange. Triage Agent sends your workspace’s custom escalation message (or “I’ll pass this to a technician.” if none is set), stands down, and hands the ticket to a human. Design runbooks that converge in two or three questions. - Ask for a few fields at a time. A
formcan carry several fields and the agent will collect them in one exchange, which is cheaper than burning a step per field. - One exchange per intent variation per ticket. Two different intents can each have an exchange open on the same ticket without interfering.
- Keep field names stable. Values merge by key across steps, so reusing a name replaces the earlier answer and a new name adds to the payload. That is what makes re-asking work.
- Every request goes to the same URL with the same headers. Branch on the presence of
continuation_tokento tell a first call from a resumption. - The exchange has no expiry. It stays open on the ticket until your endpoint returns
completeor the ten-step cap is reached.
Build and test a runbook
A working order that avoids the common dead ends:1
Stand the endpoint up first
Point the API URL at a request-capture service, or at a runbook whose only job is to return
{"message": "Received."}. Trigger the intent from a test ticket and read the real payload before writing any logic against it.2
Pin the field names
Convert each argument name to snake_case by hand and confirm it against the captured payload. Renaming an argument later changes the key, so treat the names as an interface.
3
Handle empty strings
Branch on
"" for every optional argument. This is the single most common cause of a runbook treating a blank answer as a real one.4
Add the auth header
Set the shared secret on the variation and reject any request that arrives without it.
5
Add validation loops last
Get the happy path returning
complete before introducing continue. Then add one validation at a time, checking that the re-asked field name matches the original argument name when you want to overwrite it.6
Write an internal_message on every path
Success, validation failure, and hard failure. It is the only record a technician sees on the ticket.
Thread has no partner-facing automation log today, so
internal_message and your own platform’s run history are the debugging surface. Write enough into internal_message to correlate a ticket with a run id.