Text the caller from a Retell AI agent

Add a Retell custom function that texts the caller a link, an address or a booking confirmation through TextKit, in the middle of the call.

How it works

The tool is one HTTP request to POST https://api.jointextkit.com/v1/messages. Retell fills to with {{user_number}}, the caller's number, when the tool runs. The agent writes only body, the text itself. So the agent can text the person on the call and nobody else, and you never have to read a phone number out loud or trust the agent to copy one correctly.

The request carries your key in an Authorization: Bearer header, stored on the Retell side. TextKit answers with the message (id, status), which the agent can use to say "Sent."

1. Add the custom function

In your agent, open Functions, click + Add and choose Custom Function (conversation flow agents have the same custom function). Fill in:

Turn on Payload: args only so Retell sends the arguments at the top level, the shape TextKit expects, instead of wrapping them with the call object.

2. Define the parameters

Paste this JSON schema. A property with const is filled by Retell and never by the agent; one with a description is written by the agent:

{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "const": "{{user_number}}"
    },
    "body": {
      "type": "string",
      "description": "The full text to send, under 300 characters, with the link or details the caller asked for."
    }
  },
  "required": ["to", "body"]
}

{{user_number}} is the caller's number on an inbound call and the number dialed on an outbound one. TextKit answers with the message, and the agent hears the result. Retell retries a failed request only if you set max_retry; leave it at 0 so a slow answer never sends a text twice.

3. Tell the agent when to use it

When the caller asks for a link, an address or a confirmation in writing,
offer to text it to the number they are calling from. If they say yes, call
text_caller with the full text, under 300 characters, and say "Sent." when it
returns. Never read the caller's number back to them.

Test it in the sandbox

Use a test key (ssms_sk_test_...) from the API keys page and verify your own cell under Settings in the console. Then call your agent from that phone and ask for the text. A test key delivers to your verified phone for real (up to 10 a day, ending "- via TextKit sandbox"); a call from any other phone is simulated, and the message shows in the console's log tagged Test · simulated. Browser and web test calls have no caller number, so test with a real phone call.

Before you go live

• Swap in a live key (ssms_sk_live_) and buy a number; with one number on the account, from is optional. Register your use case so carriers accept the texts.
• Have the agent offer the text and send it only after the caller says yes. STOP and HELP replies are handled for you (opt-out).
• Quiet hours apply: a text sent during a call after 9pm in the caller's local time is held until 8am, unless it is a one-time code.
• US and Canadian numbers only. A send to any other number is refused, and the agent gets the error back in the tool result.

Sources

• Retell: Custom function (single and multi-prompt agents)
• Retell: Custom function (conversation flow)
• Retell: Dynamic variables