# Text the caller from a Retell AI agent

Source: https://jointextkit.com/integrations/retell
Index: https://jointextkit.com/llms.txt

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:

| Field | Value |
|---|---|
| Name | `text_caller` |
| Description | Text the caller a link, an address or a confirmation. Use only after the caller agrees to get a text. |
| Method | `POST` |
| API Endpoint | `https://api.jointextkit.com/v1/messages` |
| Headers | `Authorization`: `Bearer ssms_sk_test_...` |
| Payload: args only | On |

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:

```json
{
  "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

```text
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](/console) 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](/docs/numbers);
  with one number on the account, `from` is optional.
  [Register your use case](/docs/compliance) 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](/docs/opt-out)).
- [Quiet hours](/docs/compliance-checks#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)](https://docs.retellai.com/build/single-multi-prompt/custom-function)
- [Retell: Custom function (conversation flow)](https://docs.retellai.com/build/conversation-flow/custom-function)
- [Retell: Dynamic variables](https://docs.retellai.com/build/dynamic-variables)