pinecallDocs
Integrations / SMS

SMS

Text messages on a Twilio number, answered by the same agent, on the same number as its calls.

Answer text messages on a Twilio number with the same agent that answers its calls. Each contact is one conversation, in writing, and your team reads and joins it from the console like any call.

How it works#

SMS is one more channel of a number. The same number can answer the phone, WhatsApp and SMS at once, each with its own agent if you want. When a contact texts the number:

Your agent's code does not change. The call's channel is sms, which is written, not spoken, and the prompt tells the model to write plain, short text: Pinecall's own words, or yours with channelRules = { sms: "…" } (The prompt).

Connect a number#

SMS needs a number of a Twilio account Pinecall knows: your own (Twilio, added once with pinecall carriers add twilio), or a number you bought on Pinecall. A number that reaches Pinecall through another carrier or your own PBX cannot answer SMS here: only Twilio's API lets Pinecall point a number's messages.

See what will happen#

Terminal
$ pinecall numbers import +14155550134 --agent front-desk --channel sms --dry-run
  twilio: +14155550134's messages posted to this box: to do
  route: +14155550134 to front-desk in the sandbox: to do
  nothing written: drop --dry-run to do it

Do it#

Terminal
$ pinecall numbers import +14155550134 --agent front-desk --channel sms --prod

Pinecall sets the number's messaging webhook at Twilio (the A message comes in field of the number) to its own address, and routes the number's SMS to the agent. The number's calls are not touched: they stay on the trunk they are on.

Text the number#

Send it a message from your phone. The agent answers in a few seconds, and the conversation appears in the console under Calls (pick SMS in Showing to see those alone).

From an assistant connected to Pinecall (Connect Claude or ChatGPT), the same is the numbers tool: "import +14155550134 for front-desk on the sms channel".

If the number's messages already go to another service, the import is refused and says where they go now: 409 +1718…'s messages go to https://… now. Add --move to take them. The other service stops receiving that number's SMS the moment you do.

In the United States a 10-digit number only delivers SMS once its Twilio account registered it for A2P 10DLC. Until then Twilio accepts the agent's reply and reports it undelivered (error 30034). Receiving works either way. Register the number in Twilio's console, under Messaging.

A reply Twilio refuses outright is an error on the conversation (sms_not_sent), with Twilio's own sentence. "Permission to send an SMS has not been enabled for the region…" (error 21408) means the account does not send to that country yet: enable it in Twilio's console, under Messaging ▸ Settings ▸ Geo permissions.

The same from the console: Numbers ▸ Add a number ▸ SMS, or the SMS section of an agent's Channels tab. Pick the number, read the two steps, confirm.

What the agent reads and sends#

Reads The text of the message. An audio attached by MMS (a phone's "audio message") is transcribed by the same ears your calls use and read as what it says. A picture or any other attachment is dropped.
Sends Plain text, from the number the contact wrote to. A reply over 1,600 characters goes out as several messages.
Read receipts, typing SMS has neither: nothing is shown to the contact while the model writes.
Delivery status What Twilio says of each reply (sent, delivered, undelivered, failed) is a message.status event on the conversation, a failure with Twilio's error code.

The agent writes first#

An agent can send the first message: a reminder, a confirmation after a phone call, a link the caller asked for.

Terminal
pinecall text reminder +14155550142 "Ana, your cleaning is tomorrow at 9:30. Reply here to change it."
From How
your terminal pinecall text <agent> <number> "<words>", with --from when the agent answers SMS at several numbers
your backend, or a tool of the agent POST /v1/agents/{slug}/text with { "to": "+14155550142", "text": "…" }, on a key that opens talk
a flow of your app step.text(number, Agent, "…"), in TypeScript, Python and Ruby
an assistant connected by MCP its text tool

The words are sent as they are, from a number the agent answers SMS at, and they open the conversation: what the contact answers reaches the agent with those words before it, and with what they last said to each other on any channel. Somebody must be running the agent.

A first message passes the same guards a call the agent places does, and one that is refused sends nothing and says which guard refused it: a number that never called or wrote to you, a +1 number with no consent on file, the hours and the pace of your policy. The hours and the daily pace are the calls' own, one count for both: under the United States' rules a text is a call. A contact whose conversation is still open is simply written on it. A contact who texted STOP is written to by nobody, whatever consent you hold.

A contact who texts STOP#

A contact who texts STOP is written to no more. It is not something your agent decides:

  • The words. STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE and OPTOUT, as the whole message, whatever their case or punctuation. Add the words your contacts use in their language with pinecall data policy --sms-stop-words BAJA,ALTO.
  • What happens. The number goes on your do-not-call list before the model reads anything, the conversation ends, and nothing more is sent. What the contact writes after is not answered, until they text START, UNSTOP or YES, which lifts it. A number on the list is not called either.
  • In other words. Somebody who writes "please stop texting me" did not use a keyword, and must be honoured all the same. Every SMS conversation gives the model a tool for it (stop_messages): the agent takes them off, they are told once, and the conversation ends. From your own code it is this.call.optOut(), as on a phone call.
  • What they are told. Twilio confirms a stop word itself on a long code and blocks the number for that contact, so Pinecall sends nothing after one. When the agent took the contact off, the carrier knew nothing of it, and Pinecall sends one sentence: "You will not receive more messages from this number. Reply START to get them again." Write your own with pinecall data policy --sms-stop-reply '…', or send none with --no-sms-stop-reply. The same three settings are on the console's Data & privacy ▸ Rules screen.
  • HELP. Twilio answers HELP and INFO itself on a long code. Set --sms-help-reply '…' to answer it yourself where the message reaches Pinecall: your name, how to reach a person, and that STOP stops the messages.

Who stopped, when, and with which words is pinecall data consent <number>; the whole list is pinecall data dnc. An assistant connected by MCP reads and sets the same with its compliance tool.

These are the rules of the United States (the TCPA and the carriers' own, the CTIA's): a business that texts needs the contact's consent, says who it is, honours any reasonable request to stop, and may confirm it once. Pinecall keeps the list and enforces it; getting the consent of whoever you text first, and registering the number for A2P 10DLC, are yours.

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. If nobody is running the agent when a message arrives, the message waits, and it is answered the moment a process holds the agent again.

The agent remembers the conversation before. A new conversation opens on what this contact and the agent last said to each other, on any channel of the same agent: an SMS after a WhatsApp thread, or after a phone call, goes on from there, and the agent does not greet them again. It carries the last ten conversations at most.

In the console, SMS and WhatsApp conversations are in Calls with every other conversation, one thread per contact; Showing narrows the list to SMS or WhatsApp. One still open is listed under Open, waiting for a reply: it is never counted as a live call. A person with the supervise scope can write into an open conversation from the desk, take it over, and hand it back.

What it costs#

Each reply counts against your org's messages and llm_tokens limits (Limits & provider keys). The carrier's charge is by segment: 160 characters of the basic alphabet, or 70 once the message has an accent outside it or an emoji, and a long message is several. Messages received and sent both count.

The number is Who bills the segments
in your own Twilio account Twilio, on your account. Pinecall adds nothing.
bought on Pinecall Pinecall, per segment, on your plan: a number of segments included each month, then a price a segment (pricing).

A conversation's summary says how many segments it exchanged (sms_segments).

Stop answering SMS#

Terminal
$ pinecall numbers drop +14155550134 --channel sms --prod

The number goes on answering the phone, and WhatsApp if it does. Pinecall takes its own address off the number's messaging webhook at Twilio, so its messages go nowhere until you point them elsewhere.

Next steps#