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#
$ 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#
$ 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--moveto 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
erroron 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.
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,REVOKEandOPTOUT, as the whole message, whatever their case or punctuation. Add the words your contacts use in their language withpinecall 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,UNSTOPorYES, 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 isthis.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
HELPandINFOitself 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#
$ 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.