8x8 Workflow Definition Management API

openapi: 3.2.0
info:
  title: Automation Workflow Definition Management API
  version: '1.0'
  description: API for managing workflows on 8x8 Automation
  contact:
    name: 8x8 Inc
    url: https://cpaas.8x8.com
    email: cpaas-support@8x8.com
  termsOfService: https://cpaas.8x8.com/sg/terms-and-conditions/
servers:
- url: https://automation.8x8.com
security:
- bearerAuth: []
tags:
- name: Workflow Definition Management
paths:
  /api/v1/accounts/{accountId}/definitions:
    parameters:
    - $ref: '#/components/parameters/accountId'
    get:
      operationId: get-all-definitions
      tags:
      - Workflow Definition Management
      summary: Retrieve a list of active workflow definitions.
      description: Use this resource to explore currently active definitions. Workflows are started based on these definitions when the trigger conditions are met. Use the parameters `limit` and `offset` to paginate through the definitions list.
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of workflow definitions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/definition'
              examples:
                definition:
                  $ref: '#/components/examples/definitions'
    post:
      operationId: create-definition
      tags:
      - Workflow Definition Management
      summary: Create a new workflow definition
      description: Use this resource to create and activate a new workflow definition.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/definitionInput'
            examples:
              definitionInput:
                $ref: '#/components/examples/definitionInput'
      responses:
        '201':
          description: Newly created workflow definition.
          headers:
            Location:
              schema:
                type: string
              description: Path to the newly created workflow definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/definition'
              examples:
                definitionInput:
                  $ref: '#/components/examples/definition'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionError'
  /api/v1/accounts/{accountId}/definitions/{definitionId}:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/definitionId'
    get:
      operationId: get-specific-definition
      tags:
      - Workflow Definition Management
      summary: Retrieve the version history of a workflow definition.
      description: Use this resource to explore different versions of a workflow definition. Results are ordered in the descending order of the version.
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of definitions. If there are no definitions by the specified definition id, an empty list is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/definition'
              examples:
                definition:
                  $ref: '#/components/examples/definitionVersions'
        '400':
          description: Definition id is invalid (not a valid uuid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionIdError'
    put:
      operationId: update-existing-definition
      tags:
      - Workflow Definition Management
      summary: Update workflow definition
      description: Use this resource to update an existing workflow definition. Updating a workflow definition creates and registers a new version of the definition and preserves the old definition in version history. This ensures that any workflows that have already been started from the old version runs to completion while new workflows are started based on the latest version of the workflow definition.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/definitionInput'
            examples:
              definitionInput:
                $ref: '#/components/examples/definitionInput'
      responses:
        '200':
          description: Updated workflow definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/definition'
              examples:
                definitionInput:
                  $ref: '#/components/examples/definition'
        '400':
          description: Request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionError'
        '404':
          description: Workflow definition is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/definitionNotFoundError'
    delete:
      operationId: delete-definitions
      tags:
      - Workflow Definition Management
      summary: Delete workflow definition
      description: Use this resource to delete workflow definitions. Specify the version of the definition to delete in the query parameter. If no version is specified, all versions of the definition will be deleted. Deleting a definition cancels any active event subscriptions, terminates all active workflows, and deletes workflow execution logs that are based on the definition that is being deleted. Once a workflow is deleted, there is no way to reverse the operation.
      parameters:
      - $ref: '#/components/parameters/version'
      responses:
        '202':
          description: Response indicating that a task has been scheduled to delete the workflow definition.
        '400':
          description: Definition id is invalid (not a valid uuid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionIdError'
        '404':
          description: Workflow definition is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/definitionNotFoundError'
  /api/v1/accounts/{accountId}/definitions/{definitionId}/workflows:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/definitionId'
    post:
      operationId: start-workflow-instance
      tags:
      - Workflow Definition Management
      summary: Test workflow definition
      description: Use this resource to test workflow definition by starting workflow instances. This endpoint is useful for testing your workflows without involving external triggers like inbound messages.
      parameters:
      - schema:
          type: integer
          minimum: 1
        in: query
        name: version
        description: Version of the definition to test. If not specified, latest version is used.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Workflow data required by the workflow. For instance, if you are trying to test a workflow that is supposed to be started by an inbound chat apps message, the request data should simulate an actual inbound webhook call. If you are unsure what the webhook payload is like for your account, please refer to [webhook object structure](/connect/reference#webhook-object-structure) or contact support.
            example:
              namespace: ChatApps
              eventType: inbound_message_received
              description: ChatApps inbound message
              payload:
                umid: 9e09ac86-bd74-5465-851d-1eb5a5fdbb9a
                subAccountId: test_subaccount_id
                timestamp: '2016-01-01T14:34:56.017Z'
                user:
                  msisdn: xxxxxxxxxx
                  channelUserId: test_user_id
                  name: test_user
                recipient:
                  channel: whatsapp
                  channelId: 269a57f4-3522-eb11-8278-00155d9f27ac
                type: text
                content:
                  text: Welcome to 8x8 Automation!
      responses:
        '201':
          description: A new workflow instance has been started from the specified workflow.
          headers:
            Location:
              schema:
                type: string
              description: Path to the newly started workflow instance.
        '400':
          description: Definition id is invalid (not a valid uuid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionIdError'
        '404':
          description: Workflow definition is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/definitionNotFoundError'
components:
  schemas:
    waitForDTMFStep:
      allOf:
      - $ref: '#/components/schemas/step'
      type: object
      description: Step to make the workflow wait for a DTMF response from an end-user.
      required:
      - stepType
      - inputs
      - outputs
      properties:
        stepType:
          type: string
          enum:
          - WaitForDTMF
          default: WaitForDTMF
          description: Type of the step.
        inputs:
          type: object
          description: Input properties supported by the wait for DTMF step.
          properties:
            dtmfRequestId:
              type: string
              description: Client request id or the uid of the DTMF response. Recommendation is to set the client request id in the voice message step, save it to workflow context and reference it here. If you did not set a client request id in the voice message step, save the uid of the voice message response to workflow context and reference it here.
            timeout:
              type: string
              description: Timeout in the format "d.HH:mm:ss". For example, "1.6:30:15" indicates the workflow to move on if a reply from the user is not received within 1 day, 6 hours, 30 minutes, and 15 seconds. If the timeout is in days, "HH:mm:ss" can be omitted. For instance, "2" waits for 2 days before timing out.
              default: 1.00:00:00
        outputs:
          type: object
          description: Output properties supported by the wait for DTMF step.
          required:
          - dtmfData
          properties:
            dtmfData:
              type: object
              description: DTMF response data returned by the voice messaging API. Refer to [voice messaging API documentation](/connect/reference#voice-messaging-api-1) for more information.
              example:
                uid: AA562920-DD44-11EB-8FDE-A7A1C7823C5F
                status:
                  code: DTMF
                  timestamp: '2021-07-05T03:54:31.271Z'
                destination: xxxxxxxxxx
                clientRequestId: 974eccfc-0607-4a99-a129-f9ee718e5fc1
                actionDetails:
                  dtmf: '2'
        selectNextStep:
          type: object
          description: Steps to execute depending on the DTMF code. Presence or absence of the `dtmfData` in the outputs indicates whether a reply was received within the timeout. Alternatively, you can set the `nextStepId` to a `Branch` step and check the conditions there.
          example:
            dtmf_1: '{{data.dtmf == ''1''}}'
            dtmf_2: '{{data.dtmf == ''2''}}'
            no_reply: '{{data.dtmf == null}}'
            invalid_dtmf: '{{data.dtmf != null && data.dtmf != ''1'' && data.dtmf != ''2''}}'
    status:
      type: string
      enum:
      - enabled
      - disabled
      description: "The status property allows to deactivate an existing workflow definition or to save a new one, without making it active. \n  * enabled (this workflow definition is active and will start based on the trigger)\n  * disabled (this workflow definition is not active and will not start, regardless of the trigger)"
      default: disabled
    step:
      description: Step defines an activity to be performed when the workflow is running.
      type: object
      properties:
        id:
          type: string
          description: Step id. Step id must be unique within the workflow definition.
      required:
      - id
    waitForReplyStep:
      allOf:
      - $ref: '#/components/schemas/step'
      type: object
      description: Step to make the workflow wait for a reply from an end-user.
      required:
      - stepType
      - inputs
      - outputs
      properties:
        stepType:
          type: string
          enum:
          - WaitForReply
          default: WaitForReply
          description: Type of the step.
        inputs:
          type: object
          description: Input properties supported by wait for reply step.
          required:
          - from
          - channel
          properties:
            from:
              type: string
              description: Phone number or channel user id of the user for whose reply the workflow is waiting for. If the channel is SMS, `from` should be the msisdn. If the channel is a chat apps channel, `from` should be based on the channel user id of the inbound message.
            channel:
              type: string
              description: Messaging channel like sms, whatsapp, etc. For a complete list, refer to [channel type values](/connect/reference#list-of-supported-chatapps-channels).
            timeout:
              type: string
              description: Timeout in the format "d.HH:mm:ss". For example, "1.6:30:15" indicates the workflow to move on if a reply from the user is not received within 1 day, 6 hours, 30 minutes, and 15 seconds. If the timeout is in days, "HH:mm:ss" can be omitted. For instance, "2" waits for 2 days before timing out.
              default: 1.00:00:00
        outputs:
          type: object
          description: Outputs supported by wait for reply step.
          required:
          - reply
          properties:
            reply:
              type: object
              description: Inbound message data. Exact nature of the payload depends on the version of the inbound message webhook configured for your account. Refer to [webhook object structure](/connect/reference#webhook-object-structure) for more information.
        selectNextStep:
          type: object
          description: Steps to execute depending on whether a reply is received or not. Presence or absence of the reply in the outputs indicates whether a reply was received within the timeout. Alternatively, you can set the `nextStepId` to a `Branch` step and check the conditions there.
          example:
            reply_received: '{{data.reply != null}}'
            no_reply_received: '{{data.reply == null}}'
        nextStepId:
          type: string
          description: Step id of the step to be executed after the current step. If not set, workflow terminates after executing the current step. Do not use `nextStepId` and `selectNextStep` at the same time. Use one or the other.
    chatAppsMessageStep:
      allOf:
      - $ref: '#/components/schemas/step'
      type: object
      description: Step to send a chat apps message.
      required:
      - stepType
      - inputs
      properties:
        stepType:
          type: string
          enum:
          - ChatAppsMessage
          default: ChatAppsMessage
          description: Type of the step.
        inputs:
          type: object
          description: Input parameters supported by the chat apps message step. All input parameters can be dynamically computed using JavaScript expressions.
          required:
          - subAccountId
          - user
          - type
          - content
          properties:
            subAccountId:
              type: string
              description: Chat apps enabled 8x8 subaccount id.
            user:
              type: object
              description: Recipient details. User object depends on the channel message is being sent to. Refer to [chat apps documentation](/connect/reference#send-message) for more information.
            type:
              type: string
              description: Message content type. For a list of supported content types, please refer to [chat apps documentation](/connect/reference#send-message).
            content:
              type: object
              description: Message content. Message content depends on the type of content being sent. Refer to [chat apps documentation](/connect/reference#send-message) for more information.
            clientMessageId:
              type: string
              description: Unique message identifier provided by the client.
        outputs:
          type: object
          description: Output properties supported by ChatAppsMessage step.
          properties:
            umid:
              type: string
              description: Unique message id assigned by the 8x8 messaging platform.
            status:
              type: string
              description: Last known status of the message.
            description:
              type: string
              description: Detailed description of the message status.
            requestId:
              type: string
              description: Unique id of the chat apps message request. If the request failed before a umid is assigned by the messaging platform, request id can be used to troubleshoot the error.
        nextStepId:
          type: string
          description: Step id of the step to be executed after the current step. If not set, workflow terminates after executing the current step.
    error:
      type: object
      description: Error response.
      properties:
        code:
          type: integer
          description: Error code.
        message:
          type: string
          description: Description of the error.
        errorId:
          type: string
          description: Unique error id.
        timestamp:
          type: string
          description: Timestamp when the error occurred.
      required:
      - code
      - message
      - errorId
      - timestamp
    definition:
      allOf:
      - $ref: '#/components/schemas/definitionInput'
      - type: object
        required:
        - accountId
        - id
        - version
        - createdAt
        properties:
          accountId:
            type: string
            description: 8x8 account id.
          id:
            type: string
            description: Unique definition id.
          version:
            type: integer
            minimum: 1
            description: Version of the definition. When a definition is updated, version number is automatically incremented.
          createdAt:
            type: string
            minLength: 1
            description: Timestamp when the definition was created.
    voiceMessageStep:
      allOf:
      - $ref: '#/components/schemas/step'
      type: object
      description: Step to make the workflow wait for a reply from an end-user.
      required:
      - stepType
      - inputs
      properties:
        stepType:
          type: string
          enum:
          - VoiceMessage
          default: VoiceMessage
          description: Type of the step.
        inputs:
          type: object
          description: Input properties supported by the voice message step.
          required:
          - action
          - params
          properties:
            subAccountId:
              type: string
              description: Voice enabled subaccount id.
            clientRequestId:
              type: string
              description: Unique identifier to reference the voice the message. JavaScript helper function `uuid()` can be used to generate a uuid.
            action:
              type: string
              enum:
              - say
              - say&capture
              - playFile
              default: say
              description: Action to be performed as part of the voice message. Refer to [voice messaging API documentation](/connect/reference#voice-messaging-api-1) for more information.
            params:
              type: object
              description: Voice message parameters. Depends on the voice message action. Refer to [voice messaging API documentation](/connect/reference#voice-messaging-api-1) for supported voice message parameters.
        outputs:
          type: object
          description: Supported output properties by the voice message step.
          required:
          - response
          properties:
            response:
              type: object
              description: HTTP response message received from the voice messaging API. Refer to [voice messaging API documentation](/connect/reference#voice-messaging-api-1) for more information.
        nextStepId:
          type: string
          description: Step id of the step to be executed after the current step. If not set, workflow terminates after executing the current step. Do not use `nextStepId` and `selectNextStep` at the same time. Use one or the other.
    smsStep:
      allOf:
      - $ref: '#/components/schemas/step'
      description: Step to send a SMS.
      properties:
        stepType:
          type: string
          enum:
          - SMS
          default: SMS
          description: Type of the step.
        inputs:
          type: object
          description: Input parameters supported by the SMS step. All input parameters can be dynamically computed using JavaScript expressions.
          required:
          - subAccountId
          - destination
          - text
          properties:
            subAccountId:
              type: string
              description: SMS enabled 8x8 subaccount.
            destination:
              type: string
              description: Valid phone number.
            text:
              type: string
              description: Content of the SMS.
            country:
              type: string
              description: Two letter country code of the destination phone number.
            source:
              type: string
              description: Sender id.
            clientMessageId:
              type: string
              description: Client message id to identify the SMS on the client platform.
            encoding:
              type: string
              description: "Messaging encoding type. Supported encodings are\n  * AUTO (automatically detect encoding)\n  * GSM7\n  * UCS2"
            scheduled:
              type: string
              description: ISO 8601 formatted date and time to send the SMS at a future time.
            expiry:
              type: string
              description: ISO 8601 formatted date and time after which the message will not be sent.
            dlrCallbackUrl:
              type: string
              description: Callback URL to receive delivery receipts.
        outputs:
          type: object
          description: Step output values that are available for saving to workflow context.
          properties:
            umid:
              type: string
              description: Unique message id assigned by the 8x8 messaging platform.
            status:
              type: string
              description: Last known status of the message.
            description:
              type: string
              description: Detailed description of the message status.
            destination:
              type: string
              description: Phone number to which the message was sent.
            encoding:
              type: string
              description: Encoding used to send the message.
            clientMessageId:
              type: string
              description: Client message id sent when the message was being sent.
        nextStepId:
          type: string
          description: Step id of the step to be executed after the current step. If not set, workflow terminates after executing the current step.
      type: object
    httpRequestStep:
      allOf:
      - $ref: '#/components/schemas/step'
      type: object
      description: Step to make a HTTP request.
      required:
      - inputs
      - stepType
      properties:
        stepType:
          type: string
          enum:
          - HttpRequest
          default: HttpRequest
          description: Type of the step.
        inputs:
          type: object
          description: Input properties supported by HTTP request step.
          required:
          - url
          - method
          properties:
            url:
              type: string
              description: URL to make the HTTP request to.
            method:
              type: string
              description: HTTP method to use when making the HTTP request. All standard HTTP methods like GET, POST, PUT, DELETE, PATCH, etc are supported.
            headers:
              type: object
              description: Map of HTTP headers to use in the request. Note that for Content-Type header, we only currently support `application/json`.
              properties:
                Authorization:
                  type: string
                  description: Authorization header.
                Accept:
                  type: string
                  description: Accept header.
            parameters:
              type: object
              description: Map of query parameters to use in the request.
              properties:
                query_param1:
                  type: string
                  description: An example query parameter.
            body:
              type: object
              description: Object containing request data. The object will be serialized as JSON before sending the request.
            timeoutSeconds:
              type: integer
              description: HTTP request timeout. Default timeout is 5 seconds.
        outputs:
          type: object
          description: Output properties supported by http request step.
          properties:
            responseCode:
              type: integer
              description: HTTP response status code received from the server.
            reasonPhrase:
              type: string
              description: HTTP response message that summarizes the meaning of the HTTP status code.
            responseBody:
              type: object
              description: HTTP response data.
        nextStepId:
          type: string
          description: Step id of the step to be executed after the current step. If not set, workflow terminates after executing the current step.
    trigger:
      type: string
      enum:
      - inbound_sms
      - inbound_chat_apps
      - http_request
      description: "Triggers are external events that start workflows. Supported triggers are\n  * inbound_sms (starts workflows when the account receives a SMS.)\n  * inbound_chat_apps (starts workflows when the account receives a message via a chat apps channel).\n  * http_request (starts workflows when a HTTP request is made to the trigger)."
    definitionInput:
      type: object
      required:
      - accountId
      - trigger
      - definition
      properties:
        subAccountId:
          type: string
          description: 8x8 subaccount id. If subaccount id is set, workflows with triggers like inbound message will only be started when that subaccount receives a message. If the subaccount id is null, workflows will be started when any subaccount under your account receives an inbound message.
        trigger:
          $ref: '#/components/schemas/trigger'
        status:
          $ref: '#/components/schemas/status'
        definition:
          type: object
          required:
          - name
          - steps
          properties:
            name:
              type: string
              description: Descriptive name for the definition. Name does not need to be unique.
            steps:
              type: array
              description: Collection of steps that defines the activities to be executed when a workflow from the definition is run.
              items:
                anyOf:
                - $ref: '#/components/schemas/smsStep'
                - $ref: '#/components/schemas/chatAppsMessageStep'
                - $ref: '#/components/schemas/httpRequestStep'
                - $ref: '#/components/schemas/branchStep'
                - $ref: '#/components/schemas/waitStep'
                - $ref: '#/components/schemas/waitForReplyStep'
                - $ref: '#/components/schemas/voiceMessageStep'
                - $ref: '#/components/schemas/waitForDTMFStep'
    branchStep:
      allOf:
      - $ref: '#/components/schemas/step'
      type: object
      description: Step to dynamically create branches in the workflow.
      required:
      - stepType
      - selectNextStep
      properties:
        stepType:
          type: string
          enum:
          - Branch
          default: Branch
          description: Type of the step.
        selectNextStep:
          type: object
          description: Map containing step ids as keys and JavaScript expressions as values to dynamically choose the next steps to execute. All conditions are evaluated and tried. Therefore, if more than one condition evaluates to true, more than one step will be executed. For the default branch, condition can be set to null.
          default: null
    waitStep:
      allOf:
      - $ref: '#/components/schemas/step'
      type: object
      description: Step to make the workflow pause for a specified duration.
      required:
      - stepType
      - inputs
      properties:
        stepType:
          type: string
          enum:
          - Wait
          default: Wait
          description: Type of the step.
        inputs:
          type: object
          description: Input properties supported by wait step.
          required:
          - duration
          properties:
            duration:
              type: string
              description: Timespan in the format "d.HH:mm:ss" to pause the workflow for. For example, "1.6:30:15" makes the workflow pause for 1 day, 6 hours, 30 minutes, and 15 seconds. If the timespan is in days, "HH:mm:ss" can be omitted. For instance, "2" pauses the workflow for two days.
        nextStepId:
          type: string
          description: Step id of the step to be executed after the current step. If not set, workflow terminates after executing the current step.
  parameters:
    definitionId:
      name: definitionId
      in: path
      description: Workflow definition id.
      required: true
      schema:
        type: string
        example: 5870442f-3ddd-4657-b74c-6e17308f5230
    version:
      name: version
      in: query
      description: Version of the workflow definition.
      required: false
      schema:
        type: integer
        minimum: 1
        example: 1
    limit:
      name: limit
      in: query
      description: Number of items to include in the response.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    accountId:
      name: accountId
      in: path
      description: Account id
      required: true
      schema:
        type: string
        example: test_account_id
    offset:
      name: offset

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-workflow-definition-management-api-openapi.yml