Hellou AI Campaigns API

openapi: 3.2.0
info:
  title: HellouOne Campaigns 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: Campaigns
paths:
  /api/v1/accounts/{account_id}/campaigns:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Campaigns
      operationId: listCampaigns
      summary: List campaigns
      description: 'Every website and SMS campaign in the account. Not paginated.


        **Administrators only.**


        **Requires feature:** `campaigns`'
      x-required-feature: campaigns
      security:
      - userApiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/campaign'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
    post:
      tags:
      - Campaigns
      operationId: createCampaign
      summary: Create a campaign
      description: 'Creates a campaign. A website inbox gets an ongoing campaign shown in the widget; an SMS inbox gets a one-off campaign sent at `scheduled_at` to the `audience` labels. On a website campaign, `sender_name` and `use_bot_identity` choose who the widget card names.


        **Administrators only.**


        **Requires feature:** `campaigns`'
      x-required-feature: campaigns
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/campaign_create_update_payload'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/campaign'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/unprocessable'
  /api/v1/accounts/{account_id}/campaigns/{id}:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - name: id
      in: path
      required: true
      description: The campaign's `id` (its number within the account).
      schema:
        type: integer
    get:
      tags:
      - Campaigns
      operationId: getCampaign
      summary: Get a campaign
      description: 'One campaign by its number within the account.


        **Administrators only.**


        **Requires feature:** `campaigns`'
      x-required-feature: campaigns
      security:
      - userApiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/campaign'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
    patch:
      tags:
      - Campaigns
      operationId: updateCampaign
      summary: Update a campaign
      description: 'Changes the fields you send. Send `sender_name: null` to clear the sender name. A completed campaign cannot be changed.


        **Administrators only.**


        **Requires feature:** `campaigns`'
      x-required-feature: campaigns
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/campaign_create_update_payload'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/campaign'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/unprocessable'
    delete:
      tags:
      - Campaigns
      operationId: deleteCampaign
      summary: Delete a campaign
      description: 'Deletes the campaign. Messages it already sent stay in their conversations.


        **Administrators only.**


        **Requires feature:** `campaigns`'
      x-required-feature: campaigns
      security:
      - userApiKey: []
      responses:
        '200':
          description: Deleted. The response has no body.
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
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'
    unprocessable:
      description: The request was understood but the data is invalid.
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/validation_error'
            - $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:
    campaign:
      type: object
      properties:
        id:
          type: integer
          description: The campaign's number within the account (its `display_id`).
        title:
          type: string
        description:
          type:
          - string
          - 'null'
        account_id:
          type: integer
        inbox:
          type: object
          description: The inbox the campaign belongs to (a website, Twilio SMS or SMS inbox).
        sender:
          type: object
          description: The agent chosen as sender. An empty object when none is set.
        sender_name:
          type:
          - string
          - 'null'
          description: 'Website campaigns only. A name the widget card shows as the speaker, for example `Ana`;

            40 characters at most. Null when none is set (the card names the business once).

            '
        use_bot_identity:
          type: boolean
          description: 'Website campaigns only. When true and an AI agent is active on the inbox, the widget card

            shows that AI agent''s name and avatar. Without an AI agent the card uses `sender_name`.

            '
        message:
          type: string
        campaign_status:
          type: string
          enum:
          - active
          - completed
        enabled:
          type: boolean
        campaign_type:
          type: string
          enum:
          - ongoing
          - one_off
        scheduled_at:
          type: integer
          description: One-off campaigns only. Unix time of the send.
        audience:
          type: array
          description: One-off campaigns only. The labels whose contacts receive the message.
          items:
            type: object
        trigger_rules:
          type: object
          description: Ongoing campaigns only. `url` (a URL pattern) and `time_on_page` (seconds).
        trigger_only_during_business_hours:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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
    campaign_create_update_payload:
      type: object
      properties:
        title:
          type: string
        description:
          type:
          - string
          - 'null'
        message:
          type: string
        inbox_id:
          type: integer
          description: A website, Twilio SMS or SMS inbox of this account.
        sender_id:
          type: integer
          description: Website campaigns only. The agent shown as sender.
        sender_name:
          type:
          - string
          - 'null'
          maxLength: 40
          description: 'Website campaigns only. A name the widget card shows as the speaker; 40 characters at most.

            Send null to clear it. Ignored on SMS campaigns.

            '
        use_bot_identity:
          type: boolean
          description: 'Website campaigns only. Show the inbox''s AI agent name and avatar on the widget card.

            Ignored on SMS campaigns.

            '
        enabled:
          type: boolean
        trigger_only_during_business_hours:
          type: boolean
        trigger_rules:
          type: object
          description: Website campaigns only. `url` (an http or https URL pattern) and `time_on_page` (seconds).
        scheduled_at:
          type: string
          format: date-time
          description: SMS campaigns only. When to send.
        audience:
          type: array
          description: SMS campaigns only. The labels whose contacts receive the message.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - Label
              id:
                type: integer
    validation_error:
      type: object
      description: Validation failure for a record.
      properties:
        message:
          type: string
          description: Every validation message, joined with commas.
        attributes:
          type: array
          description: The attributes that failed validation.
          items:
            type: string
      required:
      - message
  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