# SMS tool

Configure `send_message` with an SMS template and a condition for sending it. The Assistant collects the required details from the caller and fills in the template during the call.

## Overview

Each `send_message` tool defines one message template, such as an appointment confirmation, a link, or a summary. Set:

* `descriptionOverride` to specify when to send it.
* `from` to set the sender name.
* `body` to set the message text.
* `parameters` to define the details the Assistant must collect.

During the call, the Assistant collects those details, sends the SMS to the caller, and tells the caller whether it was sent.

For example, with this configuration:

```json
{
  "from": "AcmeDental",
  "body": "Your appointment is confirmed for {date} at {time}.",
  "parameters": {
    "type": "object",
    "properties": {
      "date": { "type": "string", "description": "Appointment date, e.g. 14/10/2026" },
      "time": { "type": "string", "description": "Appointment time, e.g. 09:30" }
    },
    "required": ["date", "time"]
  }
}
```

With `date = "14/10/2026"` and `time = "09:30"`, the caller receives this SMS from `AcmeDental`: _Your appointment is confirmed for 14/10/2026 at 09:30._

Attach separate `send_message` tools for different message templates.

***

## Naming and describing the tool

`nameOverride` and `descriptionOverride` are set when you attach the tool to an Assistant. They tell the Assistant what the message is and when to send it.

| Field                 | Type   | Required | Description                                                                                                   |
| --------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `nameOverride`        | string | No       | Name of the message, e.g. `send_appointment_confirmation`. Letters, digits, `_` and `-`, up to 64 characters. |
| `descriptionOverride` | string | No       | When the Assistant should send this message. Supports `{variable}` placeholders.                              |

Give each `send_message` tool a unique `nameOverride`. The API rejects duplicate tool names on the same Assistant with `400 DUPLICATE_TOOL_NAME`.

Add `descriptionOverride` to the Tool object alongside `assistantId` and `configuration`. State the condition for sending:

```json
"descriptionOverride": "Send the appointment confirmation once the caller has agreed on a date and time."
```

***

## Configuration

| Field        | Type   | Required | Description                                            |
| ------------ | ------ | -------- | ------------------------------------------------------ |
| `from`       | string | Yes      | Sender name shown on the recipient's phone.            |
| `body`       | string | Yes      | Text of the SMS, with placeholders.                    |
| `parameters` | object | Yes      | JSON Schema of the details the Assistant must collect. |

Configure the recipient through `parameters`. A top-level `to` field is invalid. The API rejects invalid configurations when you save the tool and lists the detected problems together:

```json
{
  "status": 400,
  "code": "INVALID_TOOL_CONFIGURATION",
  "message": "Invalid send_message configuration.",
  "context": {
    "errors": [
      "from: must be 1 to 11 alphanumeric characters with at least one letter, or a {{variable}}",
      "body: must be a non-empty string"
    ]
  }
}
```

### `from`

The sender name the recipient sees instead of a phone number.

* 1 to 11 letters or digits, with at least one letter. No spaces or special characters.
* Use your brand name. Destination-country restrictions also apply: for example, [Vonage prohibits generic sender IDs such as `INFO` and `SMS` in France](https://api.support.vonage.com/hc/en-us/articles/204017483-France-SMS-Features-and-Restrictions).
* Can be a `{{variable}}`, e.g. `{{sender_name}}`, if it changes per project.

Contact Reecall to register your sender name before going live.

### `body`

The text of the SMS. Use `{x}` or `{{x}}` placeholders for the parts that change. At send time, each placeholder is replaced with:

1. the value collected by the Assistant for the parameter of the same name,
2. otherwise, the [variable](/docs/variables) or [injected data](/docs/data-injection) of the same name.

**Example:** with the injected data `contact_name = "Jane"` and the collected `date = "14/10/2026"`, `time = "09:30"`:

```text
body: Hi {{contact_name}}, your appointment is confirmed for {date} at {time}.
sent: Hi Jane, your appointment is confirmed for 14/10/2026 at 09:30.
```

:::warning{title="Unknown and secret placeholders"}

Unknown placeholders and secret variables with `isSecret: true` become empty strings. Check placeholder spelling to avoid missing content.

:::

:::warning{title="Length and encoding"}

A single SMS holds up to 160 GSM-7 units or 70 UCS-2 units. Characters outside the GSM alphabet, such as `ê`, `œ` or an emoji, require Unicode encoding; GSM extension characters consume two units. Longer messages use multiple parts with lower per-part limits. Length is not checked for you: keep `body` and your `maxLength` values short. See [Vonage's encoding guide](https://developer.vonage.com/en/messaging/sms/guides/concatenation-and-encoding).

:::

### `parameters`

A [JSON Schema](https://json-schema.org/) (draft 2020-12) of type `object` listing the details the Assistant must collect before sending. Use `description` on each property to say what to collect and in which format.

The collected values are checked against `parameters` before sending. If they do not match, nothing is sent and the Assistant asks the caller again. Use standard JSON Schema keywords to control exactly what can appear in the SMS:

| Keyword     | Example                    | Effect                                         |
| ----------- | -------------------------- | ---------------------------------------------- |
| `required`  | `["date", "time"]`         | The SMS is not sent until these are collected. |
| `pattern`   | `"^\\d{2}/\\d{2}/\\d{4}$"` | Only accepts a `DD/MM/YYYY` date.              |
| `enum`      | `["London", "Paris"]`      | Only these values can appear in the SMS.       |
| `maxLength` | `40`                       | Caps the length of a free-text value.          |

Placeholders are not replaced inside `parameters`, so `{2}` in a `pattern` stays a regex quantifier. `pattern` does not support `\p{...}`, `\u{...}` or named groups `(?<name>...)`.

***

## Recipient

By default, the SMS is sent to the caller's number.

### Sending to someone else

To let the caller have the SMS sent to another person (a relative, a colleague), add this `to` property to `parameters.properties`:

```json
"to": {
  "type": "string",
  "description": "Phone number of the person who should receive the confirmation, if not the caller. Read it back to the caller before sending."
}
```

Leave it out of `required`: when no other number is given, the SMS goes to the caller.

### Callers without a number

When no usable caller number is available and you have not declared `to`, the tool adds it as a required argument so the Assistant can ask for a recipient. If you declare `to` yourself, mark it as required when a caller number may be unavailable.

### Phone number formats

Numbers can be given in international or French national format. Anything else, or a French number with a missing or extra digit, is refused and nothing is sent.

| Input                  | Sent to             |
| ---------------------- | ------------------- |
| `06 12 34 56 78`       | `+33 6 12 34 56 78` |
| `0033 6 12 34 56 78`   | `+33 6 12 34 56 78` |
| `+33 (0)6 12 34 56 78` | `+33 6 12 34 56 78` |
| `+44 7700 900123`      | `+44 7700 900123`   |
| `06 12 34 56 7`        | Refused             |

Numbers from other countries must include their country code (`+44...` or `0044...`).

***

## Full example

This example attaches an appointment confirmation SMS to an Assistant. The Assistant collects the date and time, and the caller's name comes from injected data.

```http
POST https://newprd.reecall.io/data_next/ai/tools
Authorization: Bearer {token}
Content-Type: application/json
```

```json
{
  "definitionId": "24de7ca4-1edf-4053-8df5-a485de305b0e",
  "assistantId": "<your-assistantId>",
  "nameOverride": "send_appointment_confirmation",
  "descriptionOverride": "Send the caller a confirmation SMS once they have agreed on an appointment date and time.",
  "configuration": {
    "from": "AcmeDental",
    "body": "Hi {{contact_name}}, your appointment at Acme Dental is confirmed for {date} at {time}. To cancel, call +33 1 23 45 67 89.",
    "parameters": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Appointment date in DD/MM/YYYY format, e.g. 14/10/2026",
          "pattern": "^\\d{2}/\\d{2}/\\d{4}$"
        },
        "time": {
          "type": "string",
          "description": "Appointment time in HH:MM format (24h), e.g. 09:30",
          "pattern": "^\\d{2}:\\d{2}$"
        }
      },
      "required": ["date", "time"],
      "additionalProperties": false
    }
  }
}
```
