WhatsApp · Pinecall Docs

Connect a WhatsApp Business number and the same agent that answers your phone answers it, in writing. Each contact is one conversation, and your team reads and joins it from the console like any call.

How it works#

A WhatsApp number is a number like any other: it belongs to your org and points at one agent, in the sandbox or production, with the channel whatsapp. When a contact writes:

A conversation opensThe first message opens a written call on the process that holds the agent. The next messages join it. The agent repliesEvery reply goes out to the contact through Meta, on your number's access token. Your team watchesThe conversation is in Calls ▸ Threads, one thread per contact.

Your agent's code does not change. The call's channel is whatsapp, which is written, not spoken, and the prompt tells the model how to write for it unless you set channelRules to false (The prompt).

Connect a number#

Get the number's ID and a token from Meta#

In Meta's WhatsApp settings, copy the phone number ID of your WhatsApp Business number. Make an access token for a system user, which does not expire. A temporary token expires within a day.

Add it in Pinecall#

On production's console, open Numbers ▸ Add a number ▸ WhatsApp. Fill in the phone number ID, the access token and, if you want, a name, then Connect WhatsApp. Pinecall asks Meta for that number with that token before it keeps anything, and stores the token encrypted.

Route it to an agent#

Pick the WhatsApp number and the agent that answers it, then Connect.

The same from a terminal, the token typed on stdin:

Terminal

$ pinecall carriers add whatsapp --phone-number-id 1055… --label Clínica
WhatsApp access token:
$ pinecall numbers available --prod
$ pinecall numbers import +59829000000 --agent clinica-norte --channel whatsapp --prod

An ID or a token Meta does not open is refused in Meta's words, and nothing is kept.

pinecall numbers import works while the org holds one carrier account; with more (a Twilio account and this WhatsApp number, say), add the number from the console (Phone numbers).

Conversations#

Messages are answered one at a time, in the order they arrive. A conversation that is quiet for two hours is over: the next message opens a new one. That keeps every reply inside Meta's 24-hour window for answering a customer.

If nobody is running the agent when a message arrives, the message waits. The moment a process holds the agent again, what waited is answered, oldest first. A message older than 24 hours is dropped, because Meta no longer lets a reply through.

Each message counts against your org's messages and llm_tokens limits. A message past them ends the conversation unanswered (Limits & provider keys).

Reading and joining#

Open Calls ▸ Threads in the console. A contact is one thread, with every conversation they had with the agent. While a conversation is open, a person with the talk scope can write into it, and the message goes to the contact as the agent. A person with the supervise scope can take it over: the contact's messages are kept and the model is not asked until the conversation is released.

Once a conversation went quiet it is sealed, and nobody can write into it: the contact's next message opens a new one. Past 24 hours since the contact last wrote, Meta lets no free message through at all.

A WhatsApp number cannot place or take a phone call. It receives messages and replies from the same number.

Next steps#

Phone numbersEvery way to get a number, side by side. Supervising a live callTaking a conversation over and handing it back. The promptHow the agent writes for a written channel. WhatsApp APIMeta's webhook and the conversation, at the gateway.