Create a Custom Action from Scratch

Use Create from scratch when you need to call your own API and no template matches. You’ll configure the HTTP request, the parameters the agent extracts from the conversation, and any authentication.

Open the form

1. Go to Global Actions in the dashboard.
2. Click Create tool (top right of the Atlas Actions tab).
3. Choose Create from scratch.

Required fields

• Name — Letters, numbers, and spaces only. Shown to the agent as the action name.
• URL — Full HTTPS endpoint. Must be a valid URL.
• Description — Tells the agent when to use this action. Write it as an instruction, e.g. “Use this to look up the status of an order when the customer provides an order number.”

HTTP settings

• Method — GET, POST, PUT, PATCH, or DELETE. Defaults to POST.
• Timeout — Seconds to wait for your response. Default 30. Max wait before the agent moves on.
• Synchronous Mode — On by default. The agent pauses until your endpoint responds. Turn off for fire-and-forget actions.
• Strict Mode — When on, the agent will not fire the action until every required parameter is filled.

Parameters

Parameters are the slots the agent fills from the conversation and sends in the request body under parameters.

To add a parameter:

1. Click Add parameter.
2. Enter a Name (used as the JSON key).
3. Pick a Type:
   • string — text values
   • number — numeric values
   • boolean — true/false
   • object — a group of nested fields
   • array — a list of values or objects
4. Write a Description — this is what the agent reads to decide what to put here. Be specific.
5. Toggle Required if the agent must collect it before firing.

Nested parameters

For object parameters (or array of objects), click the expand arrow on the parameter row and use the + button to add child properties. Nesting works to any depth.

Example — a customer object with name and email children:

customer (object, required)
├── name (string, required)
└── email (string, required)

The webhook payload will arrive as:

1
{
2
  "parameters": {
3
    "customer": {
4
      "name": "Jane",
5
      "email": "jane@example.com"
6
    }
7
  }
8
}

Headers

Add any custom HTTP headers your endpoint needs (API keys, content type, custom signatures, etc.).

• Key — Header name. No spaces.
• Value — Header value. Sent verbatim on every request.

Duplicate keys are rejected.

Authentication

Three options:

• None — No auth header is added (you can still pass a static key via Headers).
• Pick an existing OAuth method — Reuse a saved Client Credentials connection.
• Add new OAuth method — Create and test a new Client Credentials connection inline.

See OAuth Credentials for the full auth setup.

Save

Click Create Custom Tool. The action appears on the Actions Added tab. From there you can attach it to one or more campaigns — see Manage Actions.

Validation rules

• Name: letters, numbers, spaces only.
• URL: must be a valid absolute URL.
• Description: required.
• Parameter names: required if you add a parameter.
• Header keys: no spaces, no duplicates.