# BlueMarlin

> BlueMarlin is the WhatsApp workspace for small businesses: a team inbox, campaigns, flexible business data (collections of records) and an AI agent on WhatsApp. This API reads and writes its collections of records (contacts, deals, anything the workspace tracks), tags, WhatsApp conversations and messages, WhatsApp templates, the do-not-contact list and the outbound webhook settings.

The docs and the API reference are generated from the public OpenAPI contract. Each operation's page states its method, path, required scope, parameters, body fields, responses and a curl example.

## Docs

- [Getting started](https://bluemarlinchat.com/api/docs.md): authentication, conventions and every operation, one page each
- [Full reference](https://bluemarlinchat.com/llms-full.txt): every operation and guide in one Markdown file
- [OpenAPI 3.1](https://api.bluemarlinchat.com/v1/openapi.json): the machine-readable contract
- [Interactive reference](https://bluemarlinchat.com/api/docs): the page for people

## API reference

- [GET /v1/conversations](https://bluemarlinchat.com/api/docs/get-conversations.md): List conversations
- [POST /v1/tags/by-phones](https://bluemarlinchat.com/api/docs/post-tags-by-phones.md): Lookup tags for many phone numbers at once
- [GET /v1/me/usage](https://bluemarlinchat.com/api/docs/get-me-usage.md): Month-to-date AI usage for the caller and their organization
- [GET /v1/collections/{collectionId}/records](https://bluemarlinchat.com/api/docs/get-collection-records.md): List records in a collection
- [POST /v1/collections/{collectionId}/records](https://bluemarlinchat.com/api/docs/post-collection-records.md): Create a record
- [POST /whatsapp/{version}/{phone_number_id}/messages](https://bluemarlinchat.com/api/docs/post-whatsapp-messages.md): Send a message (Meta Cloud API compatible)
- [GET /v1/search](https://bluemarlinchat.com/api/docs/get-search.md): Global search across records
- [GET /v1/collections](https://bluemarlinchat.com/api/docs/get-collections.md): List collections
- [GET /v1/collections/{collectionId}](https://bluemarlinchat.com/api/docs/get-collection.md): Retrieve a collection
- [GET /v1/collections/{collectionId}/records/{recordId}](https://bluemarlinchat.com/api/docs/get-collection-record.md): Retrieve a record
- [PATCH /v1/collections/{collectionId}/records/{recordId}](https://bluemarlinchat.com/api/docs/patch-collection-record.md): Update a record
- [DELETE /v1/collections/{collectionId}/records/{recordId}](https://bluemarlinchat.com/api/docs/delete-collection-record.md): Delete a record
- [GET /v1/collections/{collectionId}/records/count](https://bluemarlinchat.com/api/docs/get-collection-records-count.md): Count records in a collection
- [GET /v1/contact-restrictions](https://bluemarlinchat.com/api/docs/get-contact-restrictions.md): List contact restrictions
- [POST /v1/contact-restrictions](https://bluemarlinchat.com/api/docs/post-contact-restrictions.md): Add a contact restriction
- [GET /v1/contact-restrictions/{phoneNumber}](https://bluemarlinchat.com/api/docs/get-contact-restriction.md): Get the restriction status for a phone number
- [DELETE /v1/contact-restrictions/{phoneNumber}](https://bluemarlinchat.com/api/docs/delete-contact-restriction.md): Remove a restriction
- [GET /v1/conversations/{conversationId}](https://bluemarlinchat.com/api/docs/get-conversation.md): Retrieve a conversation
- [POST /v1/conversations/{conversationId}/archive](https://bluemarlinchat.com/api/docs/post-conversation-archive.md): Archive a conversation
- [POST /v1/conversations/{conversationId}/assign](https://bluemarlinchat.com/api/docs/post-conversation-assign.md): Assign (or unassign) a conversation to a member
- [POST /v1/conversations/{conversationId}/handler](https://bluemarlinchat.com/api/docs/post-conversation-handler.md): Set the conversation handler (AI vs human)
- [GET /v1/conversations/{conversationId}/messages](https://bluemarlinchat.com/api/docs/get-conversation-messages.md): List messages for a conversation
- [POST /v1/conversations/{conversationId}/messages](https://bluemarlinchat.com/api/docs/post-conversation-messages.md): Send a message in a conversation
- [GET /v1/conversations/{conversationId}/messages/{messageId}/media](https://bluemarlinchat.com/api/docs/get-conversation-message-media.md): Get a presigned URL for a message's media
- [POST /v1/conversations/{conversationId}/messages/{messageId}/media](https://bluemarlinchat.com/api/docs/post-conversation-message-media.md): Download media from WhatsApp and store it
- [POST /v1/conversations/{conversationId}/read](https://bluemarlinchat.com/api/docs/post-conversation-read.md): Mark a conversation as read
- [POST /v1/conversations/{conversationId}/unarchive](https://bluemarlinchat.com/api/docs/post-conversation-unarchive.md): Unarchive a conversation
- [POST /v1/conversations/{conversationId}/unread](https://bluemarlinchat.com/api/docs/post-conversation-unread.md): Mark a conversation as unread
- [POST /v1/files/bulk-external](https://bluemarlinchat.com/api/docs/post-files-bulk-external.md): Attach external URLs as files in bulk
- [GET /v1/files/download-url](https://bluemarlinchat.com/api/docs/get-files-download-url.md): Get a presigned URL for a storage key owned by the organization
- [GET /v1/me](https://bluemarlinchat.com/api/docs/get-me.md): Inspect the current authentication context
- [POST /v1/media/upload-url](https://bluemarlinchat.com/api/docs/post-media-upload-url.md): Presigned upload URL for WhatsApp message media
- [GET /v1/members](https://bluemarlinchat.com/api/docs/get-members.md): List organization members
- [GET /v1/messages](https://bluemarlinchat.com/api/docs/get-messages.md): Search messages across the organization
- [POST /v1/messages](https://bluemarlinchat.com/api/docs/post-messages.md): Send a message
- [GET /v1/records/{recordId}/tags](https://bluemarlinchat.com/api/docs/get-record-tags.md): List tags attached to a record
- [PUT /v1/records/{recordId}/tags](https://bluemarlinchat.com/api/docs/put-record-tags.md): Replace the set of tags attached to a record
- [POST /v1/records/{recordId}/tags](https://bluemarlinchat.com/api/docs/post-record-tags.md): Attach a tag to a record
- [DELETE /v1/records/{recordId}/tags/{tagId}](https://bluemarlinchat.com/api/docs/delete-record-tag.md): Detach a tag from a record
- [GET /v1/tags](https://bluemarlinchat.com/api/docs/get-tags.md): List tags
- [POST /v1/tags](https://bluemarlinchat.com/api/docs/post-tags.md): Create a tag
- [PATCH /v1/tags/{tagId}](https://bluemarlinchat.com/api/docs/patch-tag.md): Update a tag
- [DELETE /v1/tags/{tagId}](https://bluemarlinchat.com/api/docs/delete-tag.md): Delete a tag
- [GET /v1/webhooks](https://bluemarlinchat.com/api/docs/get-webhooks.md): Retrieve the organization's outbound webhook configuration
- [PUT /v1/webhooks](https://bluemarlinchat.com/api/docs/put-webhooks.md): Update the outbound webhook configuration
- [POST /v1/webhooks/regenerate-secret](https://bluemarlinchat.com/api/docs/post-webhooks-regenerate-secret.md): Regenerate the outbound webhook signing secret
- [POST /v1/webhooks/test](https://bluemarlinchat.com/api/docs/post-webhooks-test.md): Send a test event to the configured webhook URL
- [GET /v1/whatsapp/accounts](https://bluemarlinchat.com/api/docs/get-whatsapp-accounts.md): List WhatsApp Business accounts
- [GET /v1/whatsapp/accounts/{accountId}](https://bluemarlinchat.com/api/docs/get-whatsapp-account.md): Retrieve a WhatsApp Business account
- [GET /v1/whatsapp/accounts/{accountId}/templates](https://bluemarlinchat.com/api/docs/get-whatsapp-account-templates.md): List templates cached for a WhatsApp account
- [POST /v1/whatsapp/accounts/{accountId}/templates](https://bluemarlinchat.com/api/docs/post-whatsapp-account-templates.md): Create a WhatsApp message template
- [GET /v1/whatsapp/accounts/{accountId}/templates/{templateId}](https://bluemarlinchat.com/api/docs/get-whatsapp-account-template.md): Retrieve a WhatsApp template
- [PATCH /v1/whatsapp/accounts/{accountId}/templates/{templateId}](https://bluemarlinchat.com/api/docs/patch-whatsapp-account-template.md): Update a WhatsApp template (Meta API + local cache)
- [DELETE /v1/whatsapp/accounts/{accountId}/templates/{templateId}](https://bluemarlinchat.com/api/docs/delete-whatsapp-account-template.md): Delete a WhatsApp template (all language variants)
- [POST /v1/whatsapp/accounts/{accountId}/templates/sync](https://bluemarlinchat.com/api/docs/post-whatsapp-account-templates-sync.md): Synchronize templates from Meta API to local cache
- [GET /whatsapp/{version}/{waba_id}/message_templates](https://bluemarlinchat.com/api/docs/get-whatsapp-message-templates.md): List templates (Meta Cloud API compatible)
- [POST /whatsapp/{version}/{waba_id}/message_templates](https://bluemarlinchat.com/api/docs/post-whatsapp-message-templates.md): Create a template (Meta Cloud API compatible)
- [DELETE /whatsapp/{version}/{waba_id}/message_templates](https://bluemarlinchat.com/api/docs/delete-whatsapp-message-templates.md): Delete a template (Meta Cloud API compatible)
- [Webhook message.sent](https://bluemarlinchat.com/api/docs/webhook-message-sent.md): An outbound message was sent
- [Webhook contact.unsubscribed](https://bluemarlinchat.com/api/docs/webhook-contact-unsubscribed.md): A contact was blocked or opted out
- [Webhook contact.resubscribed](https://bluemarlinchat.com/api/docs/webhook-contact-resubscribed.md): A block or opt-out was lifted
- [Webhook record.created](https://bluemarlinchat.com/api/docs/webhook-record-created.md): A record was created
- [Webhook record.updated](https://bluemarlinchat.com/api/docs/webhook-record-updated.md): A record was updated
- [Webhook record.deleted](https://bluemarlinchat.com/api/docs/webhook-record-deleted.md): A record was deleted
- [Webhook whatsapp.message](https://bluemarlinchat.com/api/docs/webhook-whatsapp-message.md): Inbound WhatsApp message (relayed from Meta)
- [Webhook whatsapp.status](https://bluemarlinchat.com/api/docs/webhook-whatsapp-status.md): Message delivery receipt (relayed from Meta)
- [Webhook whatsapp.template](https://bluemarlinchat.com/api/docs/webhook-whatsapp-template.md): Template status change (relayed from Meta)

## Guides

- [WhatsApp message templates](https://bluemarlinchat.com/api/docs/whatsapp-templates.md): How to write a template Meta approves: the rules the server checks before submitting it, categories, variables and samples, buttons, languages, review and edits, rejection reasons with their fixes, and how to send one

## MCP

- [MCP server](https://mcp.bluemarlinchat.com/mcp): for an AI assistant acting for a person — OAuth, the person signs in and consents in the browser; BlueMarlin's own tools within that person's role

## WhatsApp guides

Living guides on running WhatsApp for a business, each checked against its official sources on the date shown. Every guide is also in /es, /de, /fr, /it.

- [What WhatsApp costs from 1 October 2026](https://bluemarlinchat.com/guides/whatsapp-pricing): What Meta charges for each message, what stays free, what changes on 1 October and what a normal month comes to. With every country's rates and the official sources. (last reviewed 2026-09-30)
- [WhatsApp Business with multiple users: what the app allows](https://bluemarlinchat.com/guides/whatsapp-business-multiple-users): The free app lets you run one number from your phone and up to 4 linked devices at once, but it does not share out the chats. What breaks as the team grows, what the options are and what each one costs. (last reviewed 2026-09-30)
- [WhatsApp bulk messages: how to send without getting banned](https://bluemarlinchat.com/guides/whatsapp-bulk-messaging): A broadcast list is free, but it only reaches people who have saved your number. To reach everyone without risking the number there are two paid official routes, at €0.0585 a message in Spain. (last reviewed 2026-09-30)
- [WhatsApp coexistence: Business app and API on one number](https://bluemarlinchat.com/guides/whatsapp-coexistence): Coexistence keeps your number in the WhatsApp Business app on your phone and, at the same time, on a platform built on the official API. What you need, what syncs, what stops working on the phone and what Meta charges. (last reviewed 2026-09-30)
- [AI agent for WhatsApp Business: Meta's 2026 rules and costs](https://bluemarlinchat.com/guides/whatsapp-ai-agent): An AI that serves your own business's customers is allowed on WhatsApp: since 15 January 2026 Meta only bans general-purpose assistants. It replies within 24 hours, and you pay for the message (1,000 free a month per number, then €0.0166 in Spain) plus the AI. (last reviewed 2026-09-30)
- [WhatsApp message templates: when you need one, approval, examples](https://bluemarlinchat.com/guides/whatsapp-templates): A template is the only message the WhatsApp API lets you send once 24 hours have passed since the customer's last message. Meta reviews it within 24 hours and charges by its category: in Spain, €0.0585 for marketing and €0.0166 for utility. (last reviewed 2026-09-30)
- [WhatsApp Business limits: app and API, in one table](https://bluemarlinchat.com/guides/whatsapp-limits): What the WhatsApp Business app allows (256 contacts per broadcast list, 4 devices, 50 quick replies) and what the official API allows (from 250 to unlimited people a day), with the official source for every figure. (last reviewed 2026-09-30)
- [WhatsApp Business automatic replies: the free app vs the API](https://bluemarlinchat.com/guides/whatsapp-automatic-messages): The free app has a greeting message, an away message with a schedule and up to 50 quick replies. Buttons, lists of options and a reminder to each customer need the official API. (last reviewed 2026-09-30)
- [WhatsApp and GDPR for businesses: messaging your customers](https://bluemarlinchat.com/guides/whatsapp-gdpr): Replying to someone who wrote to you, or reminding them of an appointment, needs no separate permission. A promotion does: express consent or an existing customer, and an easy opt-out in every message. (last reviewed 2026-09-30)