> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger automation

> Trigger an automation for a phone number (auto-creates contact + conversation). The automation is always resolved inside the authorized channel — an automationId from another workspace returns 404.

Authentication: API key via X-API-Key header (or Authorization: Bearer).
Permissions: User API key
Rate limit: api_automation_trigger — 20 requests/min per API user.



## OpenAPI

````yaml /api-reference/workspace.openapi.json post /api/workspace/v1/automations/trigger
openapi: 3.1.0
info:
  title: Workspace API
  version: 1.0.0
  description: >-
    Manage contacts, labels, custom fields, WhatsApp messaging, and automations
    for your workspace.


    Generate your API key in the Developer Portal (profile menu → Developer) and
    send it in the `X-API-Key` header, or as `Authorization: Bearer <key>`.
    Never put the key in the URL.


    Every endpoint accepts POST with a JSON body, and also accepts GET with the
    same parameters as query-string values. All responses use the envelope `{
    success, data?, message?, error? }`.
servers:
  - url: https://YOUR_DOMAIN
    description: Your deployment, for example https://app.example.com
security: []
tags:
  - name: Channels
  - name: Contacts
  - name: Custom Fields
  - name: Labels
  - name: WhatsApp
  - name: Automations
paths:
  /api/workspace/v1/automations/trigger:
    post:
      tags:
        - Automations
      summary: Trigger automation
      description: >-
        Trigger an automation for a phone number (auto-creates contact +
        conversation). The automation is always resolved inside the authorized
        channel — an automationId from another workspace returns 404.


        Authentication: API key via X-API-Key header (or Authorization: Bearer).

        Permissions: User API key

        Rate limit: api_automation_trigger — 20 requests/min per API user.
      parameters:
        - name: channelId
          in: query
          required: false
          description: Channel id. Auto-selects when omitted.
          schema:
            type: string
            example: ch_123
        - name: automationId
          in: query
          required: false
          description: Automation id (or use automationName).
          schema:
            type: string
            example: au_1
        - name: automationName
          in: query
          required: false
          description: >-
            Automation name (case-insensitive). One of
            automationId/automationName required.
          schema:
            type: string
        - name: phoneNumber
          in: query
          required: false
          description: Contact phone to run the automation for.
          schema:
            type: string
            example: '919876543210'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phoneNumber
              properties:
                channelId:
                  type: string
                  description: Channel id. Auto-selects when omitted.
                  example: ch_123
                automationId:
                  type: string
                  description: Automation id (or use automationName).
                  example: au_1
                automationName:
                  type: string
                  description: >-
                    Automation name (case-insensitive). One of
                    automationId/automationName required.
                phoneNumber:
                  type: string
                  description: Contact phone to run the automation for.
                  example: '919876543210'
            example:
              channelId: ch_123
              automationId: au_1
              phoneNumber: '919876543210'
      responses:
        '200':
          description: 'Success. Envelope: { success:true, data, message? }.'
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                properties:
                  success:
                    type: boolean
                    example: true
                  data: {}
                  message:
                    type: string
                  pagination:
                    type: object
                  total:
                    type: number
              example:
                success: true
                data:
                  executionId: ex_1
                  automationId: au_1
                  automationName: Welcome flow
                  status: triggered
                message: Automation triggered successfully
        '400':
          description: >-
            Missing/invalid parameters. Body has success:false plus error and
            message.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  message:
                    type: string
        '401':
          description: >-
            Missing or invalid API key (or session expired for session
            endpoints).
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  message:
                    type: string
        '403':
          description: >-
            Authenticated but not authorized — wrong permissions or cross-tenant
            resource.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  message:
                    type: string
        '404':
          description: Automation not found in this channel.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  message:
                    type: string
        '429':
          description: >-
            Rate limited. Retry after the Retry-After seconds; see RateLimit-*
            headers.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  message:
                    type: string
        '500':
          description: >-
            Unexpected server error. Body has success:false plus error and
            message.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  message:
                    type: string
      security:
        - apiKeyHeader: []
        - bearerAuth: []
components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Preferred. API key value directly.
    bearerAuth:
      type: http
      scheme: bearer
      description: Alternative. API key as the bearer token.

````