# ChatBridge

> ChatBridge Public REST API — contacts, conversations, messages, templates, tickets, and WhatsApp Flows.

- [Introduction](https://docs.chatbridge.algosmiths.com/introduction.md): ChatBridge's public REST API for contacts, conversations, messages, tickets, and WhatsApp Flows
- [Quickstart](https://docs.chatbridge.algosmiths.com/quickstart.md): Create an API key and make your first call
- [Authentication](https://docs.chatbridge.algosmiths.com/authentication.md): API keys, scopes, and the Bearer token header
- [Rate Limits](https://docs.chatbridge.algosmiths.com/rate-limits.md): Per-key request limits
- [Pagination](https://docs.chatbridge.algosmiths.com/pagination.md): How list endpoints page through results
- [Errors](https://docs.chatbridge.algosmiths.com/errors.md): Status codes, the error envelope, and validation error shape
- [SDKs & Tools](https://docs.chatbridge.algosmiths.com/sdks.md): Official SDKs, the OpenAPI spec, and importing into your tooling
- [MCP Server](https://docs.chatbridge.algosmiths.com/mcp.md): Connect your own AI agent to ChatBridge over the Model Context Protocol
- [Changelog](https://docs.chatbridge.algosmiths.com/changelog.md): What's changed in the ChatBridge public API, newest first
- [API Reference](https://docs.chatbridge.algosmiths.com/api-reference.md): Every /api/v1/ endpoint, grouped by resource
- [List broadcasts](https://docs.chatbridge.algosmiths.com/api-reference/broadcasts/list-broadcasts.md)
- [Create a broadcast draft](https://docs.chatbridge.algosmiths.com/api-reference/broadcasts/create-a-broadcast-draft.md): Resolves recipients from `filter_tags`/`filter_conv_status`, a `segment_id`, or a `list_id` (list takes precedence) and creates a **DRAFT** — this call never sends anything. A broadcast only actually sends after a separate `POST /api/v1/broadcasts/{id}/confirm/` call. `phone_number_id` is WhatsApp's…
- [Preview recipient count for a broadcast filter](https://docs.chatbridge.algosmiths.com/api-reference/broadcasts/preview-recipient-count-for-a-broadcast-filter.md): Live count + first 5 contact names for the given filter, without creating anything. Same filter precedence as POST /broadcasts/ (list_id > segment_id > filter_tags/filter_conv_status).
- [Get a broadcast](https://docs.chatbridge.algosmiths.com/api-reference/broadcasts/get-a-broadcast.md)
- [Discard a draft broadcast](https://docs.chatbridge.algosmiths.com/api-reference/broadcasts/discard-a-draft-broadcast.md): Only a DRAFT can be discarded — 409 once it's been confirmed/is running/done.
- [Confirm and send a draft broadcast](https://docs.chatbridge.algosmiths.com/api-reference/broadcasts/confirm-and-send-a-draft-broadcast.md): The only call that actually triggers sending — irreversible, WhatsApp has no unsend. Only callable on a DRAFT broadcast; 409 if it's already been confirmed/is running/done. The same compliance shield the dashboard enforces (opted-out contacts skipped at send time) applies here too, since both paths…
- [Unschedule a scheduled broadcast](https://docs.chatbridge.algosmiths.com/api-reference/broadcasts/unschedule-a-scheduled-broadcast.md): Reverts a `scheduled` broadcast to `draft` before its fire time, so it can be edited, re-confirmed, or discarded. 409 unless the broadcast is currently scheduled — once the scheduler flips it to `running` it can no longer be stopped.
- [List contacts](https://docs.chatbridge.algosmiths.com/api-reference/contacts/list-contacts.md)
- [Create a contact](https://docs.chatbridge.algosmiths.com/api-reference/contacts/create-a-contact.md)
- [Bulk import contacts](https://docs.chatbridge.algosmiths.com/api-reference/contacts/bulk-import-contacts.md): Body: `{"contacts": [{"phone": "...", "name": "...", ...}]}`. Max 5000 rows per call. Extra keys beyond phone/name/email/company/notes/tags are stored as custom attributes.
- [Get a contact](https://docs.chatbridge.algosmiths.com/api-reference/contacts/get-a-contact.md)
- [Update a contact](https://docs.chatbridge.algosmiths.com/api-reference/contacts/update-a-contact.md)
- [Delete a contact](https://docs.chatbridge.algosmiths.com/api-reference/contacts/delete-a-contact.md)
- [List notes on a contact](https://docs.chatbridge.algosmiths.com/api-reference/contacts/list-notes-on-a-contact.md): New for the public API (public_api_pytest.md § A1) — note.view/note.create already existed as grantable scopes with no endpoint to consume them until now.
- [Add a note to a contact](https://docs.chatbridge.algosmiths.com/api-reference/contacts/add-a-note-to-a-contact.md): New for the public API (public_api_pytest.md § A1) — note.view/note.create already existed as grantable scopes with no endpoint to consume them until now.
- [List custom field definitions](https://docs.chatbridge.algosmiths.com/api-reference/custom-fields/list-custom-field-definitions.md): Custom Contact/Conversation attribute schema — CRM.md § Custom fields. Not ticketing-gated; reuses the contact.view/contact.edit scopes like ContactListView.
- [Create a custom field definition](https://docs.chatbridge.algosmiths.com/api-reference/custom-fields/create-a-custom-field-definition.md): Custom Contact/Conversation attribute schema — CRM.md § Custom fields. Not ticketing-gated; reuses the contact.view/contact.edit scopes like ContactListView.
- [Get a custom field definition](https://docs.chatbridge.algosmiths.com/api-reference/custom-fields/get-a-custom-field-definition.md)
- [Update a custom field definition](https://docs.chatbridge.algosmiths.com/api-reference/custom-fields/update-a-custom-field-definition.md)
- [Delete a custom field definition](https://docs.chatbridge.algosmiths.com/api-reference/custom-fields/delete-a-custom-field-definition.md)
- [List conversations (latest message per contact)](https://docs.chatbridge.algosmiths.com/api-reference/conversations/list-conversations-latest-message-per-contact.md)
- [List messages in a conversation](https://docs.chatbridge.algosmiths.com/api-reference/conversations/list-messages-in-a-conversation.md)
- [Update conversation status/priority/tags or reassign](https://docs.chatbridge.algosmiths.com/api-reference/conversations/update-conversation-statusprioritytags-or-reassign.md): PATCH-only — status/priority/tags and reassignment share one scope (chat.assign, see public_api.md § 6 decision 5), not split like contact.edit/contact.delete are for the contacts resource.
- [Send a WhatsApp message](https://docs.chatbridge.algosmiths.com/api-reference/messages/send-a-whatsapp-message.md)
- [List message templates](https://docs.chatbridge.algosmiths.com/api-reference/templates/list-message-templates.md)
- [Create a message template](https://docs.chatbridge.algosmiths.com/api-reference/templates/create-a-message-template.md): Goes through Meta's normal PENDING → APPROVED review, same as the dashboard. Set `source_library_template_id` to adopt a pre-vetted Template Library entry (tracks provenance on the created template).
- [List macros](https://docs.chatbridge.algosmiths.com/api-reference/macros/list-macros.md)
- [Run a macro against a conversation or ticket](https://docs.chatbridge.algosmiths.com/api-reference/macros/run-a-macro-against-a-conversation-or-ticket.md)
- [List team members](https://docs.chatbridge.algosmiths.com/api-reference/team/list-team-members.md)
- [List team inboxes](https://docs.chatbridge.algosmiths.com/api-reference/team/list-team-inboxes.md)
- [List catalogue products (live Meta proxy)](https://docs.chatbridge.algosmiths.com/api-reference/catalogue/list-catalogue-products-live-meta-proxy.md): Live pass-through proxy to Meta's Catalog API — matches the internal CatalogueProductView (no local product table, see WHATSAPP_API.md § 10). catalog_id is a required query param rather than a path segment, since a workspace's linked catalogue isn't the only one its owner may have access to on Meta'…
- [Aggregated account health (phone quality, template quality, recent alerts)](https://docs.chatbridge.algosmiths.com/api-reference/account-health/aggregated-account-health-phone-quality-template-quality-recent-alerts.md)
- [List phone numbers connected to this workspace](https://docs.chatbridge.algosmiths.com/api-reference/account-health/list-phone-numbers-connected-to-this-workspace.md): Local rows synced from Meta, not a live Graph API call. Use `phone_number_id` / `whatsapp_business_account_id` from here as the `phone_number` / `whatsapp_business_account_id` values on POST /messages/.
- [List tickets](https://docs.chatbridge.algosmiths.com/api-reference/tickets/list-tickets.md)
- [Create a ticket](https://docs.chatbridge.algosmiths.com/api-reference/tickets/create-a-ticket.md)
- [Get a ticket](https://docs.chatbridge.algosmiths.com/api-reference/tickets/get-a-ticket.md)
- [Update a ticket](https://docs.chatbridge.algosmiths.com/api-reference/tickets/update-a-ticket.md)
- [Delete a ticket](https://docs.chatbridge.algosmiths.com/api-reference/tickets/delete-a-ticket.md)
- [List comments on a ticket](https://docs.chatbridge.algosmiths.com/api-reference/tickets/list-comments-on-a-ticket.md)
- [Add a comment to a ticket](https://docs.chatbridge.algosmiths.com/api-reference/tickets/add-a-comment-to-a-ticket.md)
- [Get a ticket's audit log](https://docs.chatbridge.algosmiths.com/api-reference/tickets/get-a-tickets-audit-log.md)
- [Escalate a ticket to a different agent](https://docs.chatbridge.algosmiths.com/api-reference/tickets/escalate-a-ticket-to-a-different-agent.md)
- [Mark a ticket as a duplicate of another, closing it](https://docs.chatbridge.algosmiths.com/api-reference/tickets/mark-a-ticket-as-a-duplicate-of-another-closing-it.md)
- [List ticket pipelines](https://docs.chatbridge.algosmiths.com/api-reference/ticket-pipelines/list-ticket-pipelines.md)
- [Create a ticket pipeline](https://docs.chatbridge.algosmiths.com/api-reference/ticket-pipelines/create-a-ticket-pipeline.md)
- [Get a ticket pipeline](https://docs.chatbridge.algosmiths.com/api-reference/ticket-pipelines/get-a-ticket-pipeline.md)
- [Update a ticket pipeline](https://docs.chatbridge.algosmiths.com/api-reference/ticket-pipelines/update-a-ticket-pipeline.md)
- [Delete a ticket pipeline](https://docs.chatbridge.algosmiths.com/api-reference/ticket-pipelines/delete-a-ticket-pipeline.md)
- [List stages in a pipeline](https://docs.chatbridge.algosmiths.com/api-reference/ticket-stages/list-stages-in-a-pipeline.md)
- [Create a stage in a pipeline](https://docs.chatbridge.algosmiths.com/api-reference/ticket-stages/create-a-stage-in-a-pipeline.md)
- [Update a stage](https://docs.chatbridge.algosmiths.com/api-reference/ticket-stages/update-a-stage.md)
- [Delete a stage](https://docs.chatbridge.algosmiths.com/api-reference/ticket-stages/delete-a-stage.md)
- [Reorder stages in a pipeline](https://docs.chatbridge.algosmiths.com/api-reference/ticket-stages/reorder-stages-in-a-pipeline.md): Body: `[{"id": 1, "position": 2}, ...]`. Unknown stage IDs are ignored.
- [List WhatsApp Flows (live Meta sync)](https://docs.chatbridge.algosmiths.com/api-reference/flows/list-whatsapp-flows-live-meta-sync.md)
- [Get a Flow (live Meta re-sync)](https://docs.chatbridge.algosmiths.com/api-reference/flows/get-a-flow-live-meta-re-sync.md)
- [Get endpoint metrics for a Data Exchange Flow](https://docs.chatbridge.algosmiths.com/api-reference/flows/get-endpoint-metrics-for-a-data-exchange-flow.md): 400 for Static flows — metrics only exist for Data Exchange flows.
- [List submissions for a Flow](https://docs.chatbridge.algosmiths.com/api-reference/flows/list-submissions-for-a-flow.md): Pure local read, no Meta call. Capped at 100 rows.

## OpenAPI Specs

- [openapi](/openapi.json)