Docs / Agent Workflows

Agent Workflows

A workflow turns an agent into a structured intake form. Instead of free-form chat, the agent guides the user step by step through a set of questions — collecting a name, a date, a file upload, or any other data — then submits the completed data to your backend.

Typical uses: passport applications, service requests, job applications, support tickets, registration forms.

How it works

When a workflow is attached to an agent, the agent follows a script: it asks one question at a time, validates the answer, then moves to the next step. When all required fields are filled, the agent calls an internal submit_application function that creates a Submission record and triggers delivery to your webhook or email.

Creating a Workflow

  1. Open the agent detail page for an Active agent
  2. In the Workflow section, click Add Workflow
  3. Enter a name and an optional description
  4. Add steps (see below)
  5. Configure delivery (webhook, email, or both)
  6. Write a confirmation message
  7. Click Create Workflow
  8. Return to the agent detail page and click Re-publish to activate the workflow
Re-publish required

Adding or editing a workflow marks the agent as having unpublished changes. You must re-publish the agent for the workflow to become active in conversations.

Workflow Steps

Each step corresponds to one field of data the agent collects from the user.

Field Type What the agent collects
Text Short text answer (name, ID number, city, etc.)
Long Text Multi-line free text (descriptions, reasons, comments)
Date A calendar date (birth date, appointment date, etc.)
Number A numeric value (age, quantity, amount)
Dropdown A fixed list of options. Define options as value|Label, one per line (e.g. fr|French).
Yes/No A boolean choice (do you have a valid passport? etc.)
File Upload A document upload. Specify accepted file types (e.g. .pdf,.jpg). The file is stored and its ID is included in the submission.

Each step has a key (a unique identifier used in the submitted data, e.g. full_name), a question (what the agent asks the user), and a Required toggle. Optional steps can be skipped by the user.

Delivery

When a user completes all required steps, the agent submits the data using the delivery method you configured:

Method Description
Webhook POST aqoon sends a JSON POST request to your URL with the full submission data. Suitable for integrating with your own backend or a tool like Zapier or Make.
Email Notification aqoon sends an email to the addresses you specify (one per line). Suitable for simple intake where no backend integration is needed.
Webhook + Email Both of the above.

Webhook Payload

The webhook POST body is a JSON object with the following structure: 

{
  "reference_number": "REF-20240115-0042",
  "submitted_at": "2024-01-15T10:30:00Z",
  "applicant_name": "Aminata Diallo",
  "applicant_email": "aminata@example.com",
  "collected_data": {
    "full_name": "Aminata Diallo",
    "date_of_birth": "1990-05-20",
    "document_type": "passport"
  }
}

Confirmation Message

The confirmation message is what the agent tells the user after a successful submission. Use the placeholder {reference_number} to include the submission reference: 

Thank you! Your application has been submitted. Your reference number is {reference_number}. We will contact you within 5 business days.

Managing Submissions

Each agent's completed submissions are listed on its detail page under Submissions (open the agent → Submissions). You can filter by workflow or status.

Status Meaning
Submitted Just received, delivery pending
Processing Delivery in progress
Approved Manually marked as approved
Rejected Manually marked as rejected

Open a submission to view the full collected data, update its status, and add internal notes. The applicant is not notified of status changes — that is handled by your own process.

Editing a Workflow

From the agent detail page, click Edit next to the workflow name. After saving your changes, return to the agent detail page and click Re-publish to deploy the updated workflow.

Deleting a Workflow

Click Delete this workflow? on the agent detail page. This removes the workflow and stops new submissions. Existing submissions are not deleted. Re-publish the agent after deletion.