Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: HellouOne Connectors 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: Connectors
paths:
/api/v1/accounts/{account_id}/connectors:
parameters:
- $ref: '#/components/parameters/account_id'
get:
tags:
- Connectors
operationId: listConnectors
summary: List connectors
description: 'Lists every connector available to the account (CRM, scheduling, store, help desk,
payments, billing and data services such as HubSpot, Calendly or Shopify), each
with the account''s install merged in, plus the bots a connector can be attached to.
**Administrators only.**
**Requires feature:** `bot_connectors`'
x-required-feature: bot_connectors
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/connector_list'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
post:
tags:
- Connectors
operationId: connectConnector
summary: Connect a connector
description: 'Connects a service. The token is verified with the provider first, so a wrong
token answers 422 and nothing is saved. On success the install is saved and the
connector is attached to the chosen bots in the background; poll
`GET /connectors/{id}` for progress.
The provider token is write-only: no response ever returns it.
Limited to 10 connect or update requests per account per minute.
**Administrators only.**
**Requires feature:** `bot_connectors`'
x-required-feature: bot_connectors
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connector_create_payload'
responses:
'201':
description: Connected; bots are being attached.
content:
application/json:
schema:
$ref: '#/components/schemas/connector'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
description: 'No connector with this ID is available to the account (`code: unknown_connector`).'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_error'
'409':
description: 'The connector is already connected (`code: already_connected`), or a disconnect
is still in progress (`code: disconnect_in_progress`).
'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_error'
'422':
description: 'Nothing was saved. `code` is one of: `invalid_params` (for example an unknown
action or a bot that is not eligible), `invalid_settings`, `no_eligible_bots`
(the account has no bot to attach to), `invalid_token`, `missing_scopes`,
`provider_unreachable` or `provider_error`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_error'
'429':
description: Too many connect or update requests; retry after the `Retry-After` header.
/api/v1/accounts/{account_id}/connectors/{id}:
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
required: true
description: Connector identifier from the catalogue, e.g. `hubspot`
schema:
type: string
get:
tags:
- Connectors
operationId: getConnector
summary: Get a connector
description: 'Returns one connector card with the account''s install, if any. Poll this after
connecting or changing a connector: attaching it to each bot happens in the
background, and `install.bots[].status` / `install.attach_summary` show progress.
**Administrators only.**
**Requires feature:** `bot_connectors`'
x-required-feature: bot_connectors
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/connector'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
description: 'No connector with this ID is available to the account (`code: unknown_connector`).'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_error'
patch:
tags:
- Connectors
operationId: updateConnector
summary: Update a connector
description: 'Changes a connected connector: replace the token, change settings, enable or
disable actions, or change which bots it is attached to. Fields left out are
unchanged. A new token or new settings are verified with the provider again and
issue a new invoke token, so the bots are updated in the background.
Limited to 10 connect or update requests per account per minute.
**Administrators only.**
**Requires feature:** `bot_connectors`'
x-required-feature: bot_connectors
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connector_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/connector'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
description: 'No such connector (`code: unknown_connector`), or it is not connected or is
being disconnected (`code: not_connected`).
'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_error'
'422':
description: 'Nothing was changed. `code` is one of: `invalid_params`, `invalid_settings`,
`invalid_token`, `missing_scopes`, `provider_unreachable` or `provider_error`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_error'
'429':
description: Too many connect or update requests; retry after the `Retry-After` header.
delete:
tags:
- Connectors
operationId: disconnectConnector
summary: Disconnect a connector
description: 'Disconnects the service: the stored token is dropped, the invoke token stops
working immediately, and the connector is removed from every bot in the
background. The response shows the install as `disconnected`.
**Administrators only.**
**Requires feature:** `bot_connectors`'
x-required-feature: bot_connectors
responses:
'202':
description: Disconnected; bots are being updated.
content:
application/json:
schema:
$ref: '#/components/schemas/connector'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
description: 'No such connector (`code: unknown_connector`), or it is not connected or is
already being disconnected (`code: not_connected`).
'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_error'
/api/v1/connectors/invoke:
post:
tags:
- Connectors
operationId: invokeConnectorAction
summary: Invoke a connector action
description: 'Called by your bot at chat time to run one connector action. Not for dashboard
users: authenticate with the connector install''s **invoke token** (`hci_…`) as
`Authorization: Bearer `, not with an `api_access_token`. The token
identifies the account and connector; it is replaced whenever the connector is
reconnected or disconnected.
The body must be JSON (`Content-Type: application/json`) and at most 64 KB.
**Every handled outcome answers 200** with `{ok, …}`, including refusals such as
an invalid argument or a provider error, so the body can be handed to your bot''s
model as is. Other statuses are reserved for authentication, availability, body
size, media type and rate limiting.
When the action looks up the customer (for example finding their CRM record or
order status), the customer is the contact of the conversation given in
`conversation_id`, never an email or phone passed in `args`. The one exception is a
write that books for the customer (Calendly `book_appointment`): its `email` may be passed
in `args`, but the server only uses the contact''s email or an address the customer wrote
in that conversation, and otherwise answers `error: email_required` or `email_not_given`.
An unavailable slot answers `error: slot_taken`. A conversation can book once per
24 hours, and an install at most 20 bookings an hour; beyond that the action answers
`error: booking_limit`. If Calendly does not confirm a booking, the answer is
`provider_unavailable` with a `detail` telling the model not to book again.
A DataCRM `upsert_contact` or `create_opportunity` repeated in one conversation with the
same details (for an opportunity, the same title) answers the first result instead of
writing again, and `error: in_progress` while the first call is still running.
Rate limits: 120 requests per minute per token and 600 per minute per client IP.
Each account also has a daily invocation cap, reported as `error: daily_limit`.
**Requires feature:** `bot_connectors`'
x-required-feature: bot_connectors
security:
- connectorInvokeToken: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connector_invoke_payload'
responses:
'200':
description: 'The action ran (`ok: true`) or was refused (`ok: false`).'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_invocation_result'
'401':
description: Missing or unknown invoke token, or the connector was disconnected.
content:
application/json:
schema:
$ref: '#/components/schemas/connector_invocation_result'
'403':
description: 'The account no longer has the `bot_connectors` feature or is suspended
(`error: not_available`).
'
content:
application/json:
schema:
$ref: '#/components/schemas/connector_invocation_result'
'413':
description: The body is larger than 64 KB. The response has no body.
'415':
description: The body is not `application/json`. The response has no body.
'429':
description: Rate limit exceeded; retry after the `Retry-After` header.
components:
schemas:
connector_list:
type: object
properties:
payload:
type: array
description: Every connector available to this account.
items:
$ref: '#/components/schemas/connector'
eligible_bots:
type: array
description: The account's bots a connector can be attached to.
items:
type: object
properties:
id:
type: integer
name:
type:
- string
- 'null'
status:
type: string
enum:
- active
- paused
- unassigned
description: '`active` when connected to at least one active inbox, `paused` when all
its inboxes are paused, `unassigned` when it is in no inbox.
'
required:
- id
- name
- status
required:
- payload
- eligible_bots
connector_install:
type: object
description: 'An account''s connection to a connector. The provider token is write-only:
only `masked_secret`, its last four characters, is ever returned.
'
properties:
id:
type: integer
status:
type: string
enum:
- connected
- error
- disconnected
description: '`error` means the provider has repeatedly refused the token and a new one is
needed. `disconnected` means a disconnect is in progress or done.
'
masked_secret:
type:
- string
- 'null'
example: ••••••••a1b2
settings:
type: object
description: The non-secret connect fields, keyed by field `key`.
additionalProperties: true
enabled_actions:
type: array
items:
type: string
last_verified_at:
type:
- string
- 'null'
format: date-time
description: When the token was last verified with the provider.
last_error:
type:
- string
- 'null'
attach_summary:
type: string
enum:
- none
- attaching
- attached
- partial
- failed
description: 'Roll-up of `bots[].status`: `attaching` while any bot is still being updated,
`attached` when all are, `failed` when none are, `partial` otherwise, `none`
with no bots.
'
updated_at:
type: string
format: date-time
bots:
type: array
description: The bots this connector is attached to.
items:
type: object
properties:
agent_bot_id:
type: integer
name:
type:
- string
- 'null'
status:
type: string
enum:
- pending
- attaching
- attached
- attach_failed
- detaching
- detach_failed
tool_name:
type:
- string
- 'null'
description: Name of the tool the bot sees for this connector.
attached_at:
type:
- string
- 'null'
format: date-time
last_error:
type:
- string
- 'null'
description: Machine-readable reason for the last failure, e.g. `bot_tool_limit`.
required:
- agent_bot_id
- name
- status
- tool_name
- attached_at
- last_error
required:
- id
- status
- masked_secret
- settings
- enabled_actions
- last_verified_at
- last_error
- attach_summary
- updated_at
- bots
connector_invoke_payload:
type: object
properties:
action:
type: string
description: Name of an enabled action of the connector.
example: find_contact
args:
type: object
description: The action's arguments, validated against that action's own input schema.
additionalProperties: true
conversation_id:
type: integer
description: 'The conversation the bot is answering (its display ID, the number shown in the
dashboard). Actions that look up the customer use this conversation''s contact.
'
required:
- action
connector_update_payload:
type: object
description: 'Every field is optional, and an absent field is left unchanged. Sending `secret`
or `settings` verifies the connection again and issues a new invoke token.
'
properties:
secret:
type: string
description: A replacement provider token. A blank value keeps the stored one.
settings:
type: object
description: 'Fields to merge over the stored settings. A field sent blank is cleared.
'
additionalProperties:
type: string
enabled_actions:
type: array
description: The complete list of enabled action names.
items:
type: string
agent_bot_ids:
type: array
description: 'The complete list of bots to attach to. Bots left out are detached; bots added
are attached. Repeating the current list retries any that failed.
'
items:
type: integer
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
connector_create_payload:
type: object
properties:
connector_id:
type: string
description: Which connector to connect (a catalogue `id`).
example: hubspot
secret:
type: string
description: The provider token. Verified with the provider before anything is saved.
settings:
type: object
description: The connector's non-secret `auth_fields`, keyed by field `key`.
additionalProperties:
type: string
enabled_actions:
type: array
description: Action names to enable. Defaults to the actions marked `default_enabled`.
items:
type: string
agent_bot_ids:
type: array
description: 'Bots to attach the connector to, from `eligible_bots`. Defaults to every
eligible bot.
'
items:
type: integer
required:
- connector_id
- secret
connector_error:
type: object
description: An error from the connectors API, with a machine-readable code.
properties:
error:
type: string
description: Human-readable message.
code:
type: string
description: Machine-readable cause.
required:
- error
- code
connector_invocation_result:
type: object
description: 'The outcome of a connector call. Pass it to your bot''s model unchanged: on success
`data` holds the action''s result; on failure `error` says why.
'
properties:
ok:
type: boolean
data:
description: The action's result (present when `ok` is `true`). Its shape depends on the action.
error:
type: string
description: 'Present when `ok` is `false`. One of `invalid_args`, `unknown_action`,
`action_disabled`, `identity_unknown`, `identity_unverified`, `not_found`,
`provider_error`, `provider_unavailable`, `daily_limit`, `not_available`,
or a refusal code specific to a guarded write action (for example `slot_taken`,
`email_required`, `email_not_given` or `booking_limit`).
'
detail:
type: string
description: Extra context for some errors, such as which argument is invalid.
required:
- ok
connector:
type: object
description: 'One connector from the catalogue, with this account''s install merged in.
Admin-facing text (`description`, `auth_help`, labels) is in the account''s locale.
'
properties:
id:
type: string
description: Connector identifier, used as `{id}` in the connector paths.
example: hubspot
name:
type: string
example: HubSpot
category:
type: string
enum:
- billing
- commerce
- crm
- data
- payments
- scheduling
- support
description:
type: string
description: What the connector lets your bot do.
docs_url:
type: string
description: The provider's documentation for creating a token.
auth_help:
type: string
description: How to obtain the token and details the connector needs.
auth_fields:
type: array
description: 'The fields the connect form asks for. The one with `secret: true` is sent as
`secret`; the others are sent inside `settings`, keyed by `key`.
'
items:
type: object
properties:
key:
type: string
label:
type: string
secret:
type: boolean
pattern:
type: string
description: Regular expression the value must match, when the field has one.
placeholder:
type: string
required_for:
type: array
description: 'When present, the field is only required once one of these actions is
enabled.
'
items:
type: string
required:
- key
- label
- secret
actions:
type: array
description: What your bot can ask the connector to do.
items:
type: object
properties:
name:
type: string
label:
type: string
mode:
type: string
enum:
- read
- write
default_enabled:
type: boolean
description: Enabled on connect when `enabled_actions` is not sent.
required:
- name
- label
- mode
- default_enabled
install:
description: This account's install of the connector, or `null` when it was never connected.
oneOf:
- type: 'null'
- $ref: '#/components/schemas/connector_install'
required:
- id
- name
- category
- description
- docs_url
- auth_help
- auth_fields
- actions
- install
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'
parameters:
account_id:
in: path
name: account_id
required: true
description: The numeric ID of the account
schema:
type: integer
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