Skip to main content

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
Because the exchange is two-way, your automation is not limited to a single shot. It can come back and ask the customer for more information, which is what makes real onboarding and offboarding runbooks workable. See Multi-step automations.

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).
Automation URL field in the Triage Agent intent configuration
Because the URL and headers live on the variation rather than the intent, two variations of the same intent can point at two different runbooks.

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/onboard works, hooks.example.com/onboard does not.
  • Query strings are preserved, so ?code=abc123 style Power Automate and Azure Function URLs work as-is.
  • Credentials in the URL are stripped. https://user:pass@host/path is rebuilt as https://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

  1. Triage Agent detects the intent from the customer’s message.
  2. It asks the customer for the variation’s arguments and confirms the answers back to them.
  3. 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.
  4. Thread POSTs to your Automation URL and waits for your response before replying to the customer.
  5. It relays your message to the customer and writes your internal_message to the ticket as an internal note.
Step 4 is synchronous and blocks the customer-facing turn, so return a response promptly. If your runbook is long-running, acknowledge immediately and post the outcome back to the ticket by another route rather than holding the connection open. Triage Agent stays active on the ticket after a completed automation. It does not hand off to a technician on its own, so the customer can carry on the conversation, ask a follow-up, or trigger a second intent on the same ticket.
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_email and “User Name” arrives as user_name.
  • Every declared argument is always present. An argument the customer did not answer arrives as an empty string, not null and not an absent key. Test with field == "" 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:
Behaviour worth knowing:
  • error.message wins over message. If your body contains an error object with a message inside, Thread relays that string instead, on success responses as well as failures. Do not send an error object on a success.
  • A non-2xx response is still read. Thread parses the body and relays error.message or message, so you can return a useful explanation with a 4xx and 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 your message. Leave replies empty when you want your runbook to own the wording.
Always return an HTTP response. Thread does not retry, and a transport-level failure is not the same as an error response. If the host is unreachable, TLS fails, or the connection is dropped, the agent’s turn ends without a reply and the customer is left with silence. An endpoint that answers 500 with a body is strictly better than one that hangs up.

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:
  1. Your endpoint returns status: "continue" with a continuation_token and a form.
  2. Thread stores the in-progress step against the ticket, intent and variation, together with every field value collected so far.
  3. Triage Agent is prompted to ask the customer for the new fields. It phrases the question itself, so your message is context for the agent rather than a script it reads out.
  4. When the customer answers, the intent’s collection schema is temporarily replaced by your form fields, so the agent asks for exactly those and nothing else.
  5. 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) plus continuation_token at the top level.
  6. Repeat until your endpoint returns complete.
State is held against the ticket, so the exchange survives the customer walking away and replying an hour later, or the next morning. It is cleared as soon as the automation completes.

Continue response format

Each field takes the same shape as an intent argument: 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.
A continue response that omits either continuation_token or a non-empty form.fields is treated as complete. The exchange ends and the customer receives your message as the final word, so validate both before returning.

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.
Note 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.
Triage Agent then asks the customer for a corrected address in its own words, using your 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.
Step 2 response. The lookup succeeds and the runbook finishes.
Because the same field name can be re-requested, the same pattern covers any validation failure: re-ask 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.
Return a different continuation_token on each step and treat it as the only state Thread holds for you. Everything else, including which validations have already passed, should live in your own workflow.

Limits and edge cases

  • Ten round trips maximum. A continue beyond 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 form can 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_token to tell a first call from a resumption.
  • The exchange has no expiry. It stays open on the ticket until your endpoint returns complete or 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.

Troubleshooting

Next step

Build the intent that will carry the automation in Create Your First Triage Agent Intents, or plan the wider set in Building Your Magic Agents Service Catalog.