# Bow Chat Integration API

Authenticate, resolve an inbox and contact, create or reuse a conversation, send a message, and receive signed delivery events.

## What the API covers

Use the Bow Chat Integration API to connect an operating system, CRM, clinic application, or workflow service to a Bow Chat workspace. The normal send path is:

1. List inboxes and choose the intended sender.
2. Search for the contact by your stable identifier or phone number.
3. Create the contact if it does not exist.
4. Read the contact's `source_id` for that inbox.
5. Create or reuse the account-scoped conversation.
6. Send a channel-appropriate message.
7. Observe `message_updated` events until the attempt is delivered, read, or failed.

[Download the OpenAPI contract](https://docs.bow.chat/openapi/bow-chat-v1.openapi.yaml).

## Base URL and authentication

```text
https://app.bow.chat/api/v1/accounts/{account_id}
```

Send the dedicated integration token in the `api_access_token` header:

```bash
curl --request GET \
  --url https://app.bow.chat/api/v1/accounts/ACCOUNT_ID/inboxes \
  --header 'api_access_token: BOW_CHAT_TOKEN'
```

Keep the token in a server-side secret store. Do not place it in browser code, a mobile app, a URL, logs, screenshots, or a shared document. Bow Chat provisions the workspace account ID and integration credential during onboarding.

## Identifier contract

- `account_id` scopes every resource to one workspace.
- `inbox_id` identifies the sender channel.
- `contact_id` is Bow Chat's contact record.
- `identifier` should hold the stable contact ID from your system.
- `source_id` binds that contact to a particular inbox and must be used when creating a conversation.
- Conversation API paths use the account-scoped conversation display ID returned as `id`. Do not substitute an internal database ID from a webhook payload.

## First request sequence

```bash
# 1. Find the patient/contact
curl --get \
  --url https://app.bow.chat/api/v1/accounts/ACCOUNT_ID/contacts/search \
  --header 'api_access_token: BOW_CHAT_TOKEN' \
  --data-urlencode 'q=setrio-patient-84291'

# 2. If absent, create it in the sender inbox
curl --request POST \
  --url https://app.bow.chat/api/v1/accounts/ACCOUNT_ID/contacts \
  --header 'api_access_token: BOW_CHAT_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"inbox_id":14001,"name":"Ana Popescu","phone_number":"+40722123456","identifier":"patient-84291"}'
```

Then call `GET /contacts/{contact_id}/contactable_inboxes`, select the intended `inbox.id`, and store its `source_id`. See [Send a message](https://docs.boni.one/developers/send-a-message).

## Privacy for regulated data

Keep message content to the minimum needed for the communication. Health data is a special category of personal data under GDPR. Before production, the parties should document controller/processor roles, purpose and legal basis, retention, access, audit, incident response, and any data-location or subprocessors requirements.

The API is a transport and workspace contract; it does not choose the legal basis for a clinic's patient communication.

Canonical: https://docs.bow.chat/developers/overview
Version: 2
Updated: 2026-09-04T12:54:38.972Z