Hellou AI WhatsApp Flows API

openapi: 3.2.0
info:
  title: HellouOne WhatsApp Flows API
  version: 1.0.0
  description: 'The HellouOne REST API: everything the dashboard does, available to your

    own systems — CRMs, bots, BI tools and back-office automation.'
  termsOfService: https://hellou.ai/en/legal/terms/
  contact:
    name: HellouOne support
    email: support@hellou.ai
servers:
- url: https://one.hellou.ai
  description: HellouOne cloud
security:
- userApiKey: []
tags:
- name: WhatsApp Flows
  description: 'Forms sent inside WhatsApp. Each flow message sent to a contact is a *session*; list a flow''s

    sessions to report on who received, opened and submitted it, and — as an administrator, with

    every read audited — export what they answered. Pair with the `whatsapp_flow_completed`

    webhook to receive submissions as they happen.'
paths:
  /api/v1/accounts/{account_id}/whatsapp_flows/{whatsapp_flow_id}/sessions:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - name: whatsapp_flow_id
      in: path
      required: true
      description: ID of the flow
      schema:
        type: integer
    get:
      tags:
      - WhatsApp Flows
      operationId: listWhatsappFlowSessions
      summary: List a flow's sessions
      description: 'The contacts a flow was sent to, newest first. By default only **completed** sessions — the

        submissions — dated by when they were submitted; any other `status` is dated by when the flow

        was sent. Test sends from the flow editor are left out unless `include_test=true`.


        The list carries no answers. Add `include=answers` to export them: the real values, sensitive

        ones included, exactly as the conversation''s *Reveal answers* shows them. Every session

        revealed this way is recorded in the account''s audit log under the calling user, so page

        through only what you need. Answers are removed after the account''s retention window;

        such a session comes back with `answers_purged: true`.


        Administrators only.


        **Requires feature:** `whatsapp_flows`'
      x-required-feature: whatsapp_flows
      parameters:
      - name: status
        in: query
        description: One session status.
        schema:
          type: string
          enum:
          - sent
          - opened
          - in_progress
          - completed
          - expired
          - failed
          default: completed
      - name: since
        in: query
        description: 'Sessions submitted (for `completed`) or sent (otherwise) at or after this moment — an ISO 8601

          timestamp, or a date (`YYYY-MM-DD`) for the start of that day.

          '
        schema:
          type: string
      - name: until
        in: query
        description: Same, at or before this moment; a date means the end of that day.
        schema:
          type: string
      - name: include_test
        in: query
        description: Include sends to test numbers.
        schema:
          type: boolean
          default: false
      - name: include
        in: query
        description: '`answers` to add each session''s submitted answers (audited).'
        schema:
          type: string
          enum:
          - answers
      - name: page
        in: query
        description: Page number, from 1.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Sessions per page. Values above 100 are treated as 100.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/whatsapp_flow_session_list'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          description: A filter cannot be read (`reason`, for example `invalid_since` or `invalid_status`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  responses:
    unauthorized:
      description: Missing or invalid `api_access_token`, or a bot token on an endpoint bots cannot use.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    forbidden:
      description: 'Not allowed: the user''s role does not permit it, the feature is not enabled

        for the account (`reason: feature_disabled`), or the account is read-only.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    not_found:
      description: The resource does not exist in this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
  parameters:
    account_id:
      in: path
      name: account_id
      required: true
      description: The numeric ID of the account
      schema:
        type: integer
  schemas:
    error_message:
      type: object
      description: An error with a human-readable message.
      properties:
        error:
          type: string
          description: What went wrong.
        reason:
          type: string
          description: Machine-readable cause, when there is one (for example `feature_disabled`).
      required:
      - error
    whatsapp_flow_session:
      type: object
      description: One flow message sent to one contact, and how far they got.
      properties:
        id:
          type: integer
        status:
          type: string
          enum:
          - sent
          - opened
          - in_progress
          - completed
          - expired
          - failed
          description: '`sent`, `opened` and `in_progress` are open; the rest are final.'
        test:
          type: boolean
          description: Sent to a test number from the flow editor.
        flow_version:
          type:
          - integer
          - 'null'
          description: The published version the contact was sent.
        inbox_id:
          type: integer
        conversation_id:
          type: integer
          description: The conversation's display ID, as in conversation paths.
        contact:
          type: object
          properties:
            id:
              type: integer
            name:
              type:
              - string
              - 'null'
            phone_number:
              type:
              - string
              - 'null'
          required:
          - id
          - name
          - phone_number
        sent_at:
          type: string
          format: date-time
        opened_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the contact submitted the form.
        answers_purged:
          type: boolean
          description: 'Only with `include=answers`. True when the retention window already removed this session''s

            answers; `answers` is then empty.

            '
        answers:
          type: array
          description: 'Only with `include=answers`: the real submitted values, sensitive ones included. Empty for a

            session that was not completed or whose answers were purged.

            '
          items:
            type: object
            properties:
              key:
                type: string
              label:
                type: string
              value:
                description: As submitted — usually a string; a multi-select answer is an array.
              sensitive:
                type: boolean
                description: Marked sensitive in the flow; shown masked in the conversation.
            required:
            - key
            - label
            - value
            - sensitive
      required:
      - id
      - status
      - test
      - flow_version
      - inbox_id
      - conversation_id
      - contact
      - sent_at
      - opened_at
      - completed_at
    whatsapp_flow_session_list:
      type: object
      properties:
        payload:
          type: array
          description: Sessions, newest first.
          items:
            $ref: '#/components/schemas/whatsapp_flow_session'
        meta:
          type: object
          properties:
            count:
              type: integer
              description: Sessions matching the filters, across all pages.
            current_page:
              type: integer
            per_page:
              type: integer
          required:
          - count
          - current_page
          - per_page
      required:
      - payload
      - meta
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A user''s access token, from **Profile settings → Access token** in the dashboard.

        Requests act with that user''s role: administrators reach everything in their

        account, agents only what their role and visibility settings allow.

        '
    agentBotApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'An agent bot''s access token, shown to administrators on the bot''s settings page.

        Bot tokens reach a limited set of conversation and message endpoints.

        '
    platformAppApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A platform app token, issued by the installation operator. Used to provision

        accounts, users, account memberships and agent bots.

        '
    connectorInvokeToken:
      type: http
      scheme: bearer
      description: 'A connector''s invoke token (`hci_…`), sent as `Authorization: Bearer <token>`.

        Each connector install has its own; it is rotated whenever the connector is

        reconnected or disconnected, so a stale copy stops working.

        '
x-tagGroups:
- name: Guides
  tags:
  - Introduction
  - Authentication
  - Errors
  - Pagination
  - Rate limits
  - Webhook events
- name: Webhook payloads
  tags:
  - Event payloads
- name: Platform
  tags:
  - Accounts
  - Account Users
  - AgentBots
  - Users
- name: Application
  tags:
  - Account AgentBots
  - Agents
  - Automation Rule
  - Campaigns
  - Canned Responses
  - Contacts
  - Contact Labels
  - Conversation Assignment
  - Conversation Labels
  - Conversations
  - Custom Attributes
  - Custom Filters
  - Help Center
  - Inboxes
  - Integrations
  - Macros
  - Messages
  - Profile
  - Reports
  - Security Settings
  - Teams
  - Webhooks
- name: Business tools
  tags:
  - AI Classifications
  - Assignment Settings
  - Calls
  - AI Phone Lines
  - Connectors
  - ElevenLabs Integration
  - Facebook Marketing
  - HellouAI Integration
  - Knowledge Base
  - Marketing Consent
  - Plan Upgrades
  - Voice Campaigns
  - WhatsApp Campaigns
  - WhatsApp Flows
  - WhatsApp Templates
- name: Client
  tags:
  - Inbox API
  - Contacts API
  - Conversations API
  - Messages API
- name: Others
  tags:
  - CSAT Survey Page