MCP Server for Managing WhatsApp Business Platform Chats from AI Assistants like Meta Muse and Claude
Stay in the AI assistant you already use. Connect it to TimelinesAI to read your WhatsApp Business Platform chats, reply to customers, send approved templates, and assign and label chats for your team.
The TimelinesAI MCP server works with any AI assistant that supports remote MCP servers with OAuth sign-in. There’s no software to install, no server to manage, and no password to share. The assistant can only do what your TimelinesAI role allows.
What the connector can do
- Read chats, message history and message status across your WhatsApp Business Platform numbers
- Reply with free text while the customer’s 24-hour window is open
- Send Meta-approved templates, and start new chats with a template
- Assign, unassign, open and close chats, and add or remove labels
- React to messages, and see your team members and templates
What you need
- A TimelinesAI account. New accounts start with a 10-day free trial, no credit card required.
- At least one WhatsApp Business Platform (Cloud API) number connected to your workspace. New to the WhatsApp Business Platform? Connect and activate a WhatsApp Business number in Meta Business Portfolio.
- At least one approved template, if you want the assistant to start new chats or message customers outside the 24-hour window.
How to set up
Step 1: Add the connector.
In your AI assistant, add a new connector (or custom MCP server) and paste
https://mcp.services.timelines.ai/mcp/waba.Step 2: Sign in with TimelinesAI.
The assistant opens the TimelinesAI login page. Sign in, or create an account.
Step 3: Approve access.
Review the permissions on the “Authorize timelines-mcp?” page and click Authorize.
Step 4: Ask your first question.
Try “List my WhatsApp Business numbers” or “Show chats that are waiting for a reply”.
Connection details
| Setting | Value |
|---|---|
| MCP server URL | https://mcp.services.timelines.ai/mcp/waba |
| Transport | Streamable HTTP |
| Sign-in | OAuth 2.1 with PKCE (S256) and dynamic client registration |
| Authorization server | https://mcp.services.timelines.ai |
| Scopes | openidchats:readchats:writemessages:readmessages:writelabels:readlabels:writeaccounts:readworkspace:readtemplates:read |
Tools (18)
Read tools only look at data. Write tools change a chat inside TimelinesAI. Sensitive write tools send something your customer sees, and template sends are charged by Meta.
| Tool | What it does | Access |
|---|---|---|
waba_accounts | Lists the WhatsApp Business Platform numbers you can send from | Read |
waba_list_chats | Lists the chats you can see, with filters (for example, by phone number) | Read |
waba_chat_details | Shows one chat: whether the 24-hour window is open, the assignee, labels and the sending number | Read |
waba_chat_history | Shows the messages in a chat, newest first | Read |
waba_message_details | Shows one message, including the reason if it failed | Read |
waba_templates | Lists the message templates you can use | Read |
waba_template_details | Shows one template: its content, variables, status and the numbers it can be sent from | Read |
workspace_team | Lists teammates, so a chat can be assigned to one of them | Read |
waba_chat_open | Reopens a closed chat | Write |
waba_chat_close | Closes a chat | Write |
waba_chat_assign | Assigns a chat to a teammate | Write |
waba_chat_unassign | Removes the assignee from a chat | Write |
waba_chat_set_label | Adds a label to a chat | Write |
waba_chat_remove_label | Removes a label from a chat | Write |
waba_chat_send_message | Sends a free-text reply in an existing chat, only while the 24-hour window is open | Sensitive write |
waba_chat_send_template | Sends an approved template in an existing chat | Sensitive writeMeta charges for templates |
waba_start_chat | Starts a new chat with a phone number using an approved template | Sensitive writeMeta charges for templates |
waba_message_react | Adds or removes an emoji reaction on a message | Sensitive writeThe customer sees it |
Every tool is labeled as read-only or as making changes, so AI assistants can ask you to confirm before a write runs.
Tool inputs
Every tool returns the JSON response of the TimelinesAI API for that action. Required inputs are in bold. The assistant gets ids from the list tools first (for example, a chat id from waba_list_chats).
| Tool | Inputs |
|---|---|
waba_accounts | None |
waba_list_chats | All optional: waba_account_id, responsible (teammate email), closed (true or false), whatsapp_phone, with_msg (include the last message), page (50 chats per page) |
waba_chat_details | chat_id |
waba_chat_history | chat_id. Optional: from_me, after and before (ISO date or date-time), after_message and before_message (message id), sorting_order (asc or desc), page, size |
waba_message_details | message_uid |
waba_templates | Optional page |
waba_template_details | template_id |
workspace_team | None |
waba_chat_openwaba_chat_closewaba_chat_unassign | chat_id |
waba_chat_assign | chat_id, user_email (a teammate from workspace_team) |
waba_chat_set_labelwaba_chat_remove_label | chat_id, label |
waba_chat_send_message | chat_id, text |
waba_chat_send_template | chat_id, name and language of an approved template. Optional variables: header and body lists, in template order |
waba_start_chat | waba_account_id, phone (international format with a leading +), name and language of an approved template. Optional variables, as above |
waba_message_react | message_uid, reaction (one emoji, or an empty value to remove it) |
Errors and limits
When a call fails, the tool returns an error result with the HTTP status, the TimelinesAI API’s message and, where there is one, an error code. The assistant can then explain what happened and what to do next.
| Status | What it means | What to do |
|---|---|---|
| 400, 409, 422 | The request was rejected, for example a missing input or a phone number in the wrong format | Fix the input and try again |
| 401 | The sign-in is no longer valid | Reconnect the connector and sign in to TimelinesAI again |
| 403 | The user’s role or plan doesn’t allow this action | Ask a workspace Owner or Admin |
| 404 | The chat, message or template wasn’t found | Find the right id with the list tools |
| 429 | Too many requests | Wait a moment and try again |
| 5xx, or no answer within 15 seconds | Temporary problem on the TimelinesAI side | Try again later |
- 24-hour window: if the window is closed, a free-text reply is rejected. Send an approved template instead.
waba_chat_detailsandwaba_list_chatsshow whether the window is open. - Delivery: a successful send means Meta accepted the message. If delivery fails later,
waba_message_detailsshows the reason. - No duplicate sends: send tools are not retried automatically. If a send times out, check
waba_chat_historybefore sending again, so the customer doesn’t get the message twice. - Rate limits: the connector doesn’t add a rate limit of its own. Meta’s messaging limits for your WhatsApp Business Platform number still apply to template messages.
What the assistant can see
The assistant acts as the TimelinesAI user who signed in, with that user’s permissions. It never sees more than that user can see in TimelinesAI.
- Owners and Admins see every WhatsApp Business Platform number in the workspace and all of its chats.
- Team supervisors and Teammates see the numbers whose team is set to their team, and those numbers’ chats.
- Agents see the numbers assigned to them, and those numbers’ chats.
- Collaborators see only the chats assigned to them. They can reply there, but can’t start new chats.
- Assigned chats: anyone assigned to a single chat can see and reply in that chat. That doesn’t open the rest of that number.
Messaging rules
- Inside the 24-hour window (the customer wrote in the last 24 hours), the assistant can send free-text replies.
- Outside the window, or for a new chat, only Meta-approved templates can be sent. A template doesn’t reopen the window for free text.
- Templates with a media header (image, video or document) can’t be sent through the connector yet. Use templates with text variables.
- Delivery: a successful send means Meta accepted the message. Delivery can still fail later, and the assistant can check the reason.
Pricing
Using the connector is included in every TimelinesAI plan at no extra charge. Meta charges for template messages at its standard WhatsApp Business Platform rates, and the assistant tells you before it sends one.
Privacy and security
- Sign-in uses OAuth, so your AI assistant never sees your TimelinesAI password.
- The assistant can only use the data the signed-in user can access, within the scopes above.
- To disconnect, remove the connector in your AI assistant.
- See our Privacy notice for this connector and Terms. Help: support@timelines.ai.
FAQs about the WhatsApp Business Platform MCP server
Last updated: