> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS Functions in extensions.tools

> The exact JSON for adding Send SMS (Twilio, hosted SMS or NetSapiens) and Notify functions to an agent through Create Agent and Update Agent

An agent's functions are stored as entries in `extensions.tools`. To add an SMS function through the API, add the entry below to `extensions.tools` on [Create Agent](https://docs.telzino.com/api-reference/agents/create.md) or [Update Agent](https://docs.telzino.com/api-reference/agents/update.md). These are the same entries the Telzino Dashboard writes when you add the function under **Functions**.

> [!WARNING]
>
> `extensions` is replaced whole. Read the agent with [Get Agent](https://docs.telzino.com/api-reference/agents/get.md), add your entry to the existing `extensions.tools` array, and send the whole `extensions` object back. If you send only the new entry, every other function on the agent is removed.

## Which function to use

| You want to | Use | Tool `type` |
| - | - | - |
| Send texts through the organization's Twilio connection | [Send SMS via Twilio](#send-sms-via-twilio) | `twilio_sms` |
| Send texts from a Telzino hosted SMS number | [Send SMS via hosted SMS](#send-sms-via-hosted-sms) | `hosted_sms` |
| Send texts through NetSapiens | [Send SMS via NetSapiens](#send-sms-via-netsapiens) | `netsapiens` |
| Keep an existing Notify (call summary) function | [Notify](#notify) | `notification` |

The agent decides when to text, who to text and what to say from the instructions you give it in the function. See [Send SMS](https://docs.telzino.com/functions/send-sms.md) for writing them.

## Rules for every entry

The API validates each entry in `extensions.tools` against a strict schema. A key it doesn't recognise is rejected with `400`.

| Field | Type | Notes |
| - | - | - |
| `name` | string | The function's name. Use the exact names below. |
| `type` | string | One of the allowed tool types, for example `twilio_sms`, `hosted_sms`, `netsapiens` or `notification`. |
| `friendlyName` | string | Display name. |
| `description` | string | What the function does. The dashboard sets it to the same text as the instructions. |
| `condition` | string | When the function can run. SMS functions use `during_call`. |
| `url` | string | Must be a valid URL. SMS functions use an `internal://` address, shown below. |
| `method` | string | `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. The dashboard writes `POST`. |
| `headers` | array | `{ "key", "value" }` pairs. The dashboard writes `Content-Type: application/json`. |
| `parameters` | array | `{ "key", "value" }` pairs, where `value` is a string. |
| `enabled` | boolean | Optional. Not used by SMS functions. |

The schema marks every field as optional, but send the full entry as shown so the agent and both editors read it the same way.

## Send SMS via Twilio

The agent texts through the organization's [Twilio connection](https://docs.telzino.com/integrations/twilio.md). Set up the connection first in the Telzino Dashboard or the Connect App.

```json theme={null}
{
  "name": "send_sms_via_twilio",
  "type": "twilio_sms",
  "friendlyName": "Send_SMS",
  "condition": "during_call",
  "url": "internal://twilio-sms-service",
  "method": "POST",
  "headers": [{ "key": "Content-Type", "value": "application/json" }],
  "description": "If the caller requests a confirmation, send them an SMS with the appointment details.",
  "parameters": [
    { "key": "sms_instructions", "value": "If the caller requests a confirmation, send them an SMS with the appointment details." },
    { "key": "from_number", "value": "+15555550100" }
  ]
}
```

| Parameter | Required | Value |
| - | - | - |
| `sms_instructions` | Yes | When and what to text. The dashboard uses the text shown above when this is left blank. |
| `from_number` | See note | The number this agent texts from, in E.164 format. |

* **From number:** a new or changed Send SMS entry needs a From number, either in `from_number` or in the agent's `integrations.twilio.fromNumber`. If neither has one, the request is rejected with `400` and the message `Send SMS needs a From number. Add one to the function, or remove the function.` An entry that is already stored without a number is not re-checked when you send it back unchanged.
* **Twilio credentials** can't be set on an agent. Every agent in the organization uses the organization's Twilio connection. See `integrations` on [Update Agent](https://docs.telzino.com/api-reference/agents/update.md).
* Writing `integrations.twilio` through the API does **not** add this entry. Add it yourself.

## Send SMS via hosted SMS

The agent texts from one of the organization's hosted SMS numbers. Hosted SMS is set up by Telzino on request. See [Send SMS](https://docs.telzino.com/functions/send-sms.md#sms-methods).

```json theme={null}
{
  "name": "send_hosted_sms",
  "type": "hosted_sms",
  "friendlyName": "Send_Hosted_SMS",
  "condition": "during_call",
  "url": "internal://hosted-sms-service",
  "method": "POST",
  "headers": [{ "key": "Content-Type", "value": "application/json" }],
  "description": "If the caller requests a confirmation, send them an SMS with the appointment details.",
  "parameters": [
    { "key": "sms_instructions", "value": "If the caller requests a confirmation, send them an SMS with the appointment details." },
    { "key": "from_number", "value": "+15555550100" }
  ]
}
```

* `from_number` must be one of the organization's hosted SMS numbers. A new or changed number is checked when you save, and an unowned number is rejected with `400`.
* If **Hosted SMS** is locked for the organization in [Feature Administration](https://docs.telzino.com/admin-guide/dashboard/feature-administration.md), a request that **adds** this entry is refused with `403`. Sending back, editing or removing an existing entry is still allowed.
* To let the agent read the caller's replies, also add `check_hosted_sms_replies`:

  ```json theme={null}
  {
    "name": "check_hosted_sms_replies",
    "type": "hosted_sms_replies",
    "friendlyName": "Check_Hosted_SMS_Replies",
    "condition": "during_call",
    "url": "internal://hosted-sms-service",
    "method": "POST",
    "headers": [{ "key": "Content-Type", "value": "application/json" }],
    "description": "When to check whether the caller has texted back.",
    "parameters": []
  }
  ```

## Send SMS via NetSapiens

The agent texts through NetSapiens, using the agent's own SMS number as the sender. The agent needs the NetSapiens integration. See [Send SMS (Voip UCAAS)](https://docs.telzino.com/netsapiens-functions/send-sms.md).

```json theme={null}
{
  "name": "ns_send_sms",
  "type": "netsapiens",
  "friendlyName": "Send_Sms",
  "condition": "during_call",
  "url": "internal://netsapiens-service",
  "method": "POST",
  "headers": [{ "key": "Content-Type", "value": "application/json" }],
  "description": "Text the caller the office address when they ask for directions.",
  "parameters": [
    { "key": "instructions", "value": "Text the caller the office address when they ask for directions." }
  ]
}
```

* To read replies, add a second entry with the same shape, `"name": "ns_check_sms_replies"` and `"friendlyName": "Check_Sms_Replies"`.
* If **SMS Messaging** is locked for the organization in Feature Administration, a request that **adds** `ns_send_sms` or `ns_check_sms_replies` is refused with `403`. Sending back or removing an existing entry is still allowed.

## Notify

The Notify function sends a call summary at the end of the call. The Telzino Dashboard no longer offers Notify under **Add function**, but agents that already have it keep it, and the API still accepts the entry:

```json theme={null}
{
  "name": "Notify_Email",
  "type": "notification",
  "friendlyName": "Send_Email_Notification",
  "condition": "end_of_call",
  "url": "https://your-email-service.com/api/send-notification",
  "method": "POST",
  "headers": [{ "key": "Content-Type", "value": "application/json" }],
  "description": "Send a summary to frontdesk@example.com and text +15555550100 after every call.",
  "parameters": [
    { "key": "notification", "value": "Send a summary to frontdesk@example.com and text +15555550100 after every call." }
  ]
}
```

* The recipients and conditions are written in plain language in the `notification` parameter, as described on [Notify](https://docs.telzino.com/functions/notify.md). The dashboard stores the `url` above as a placeholder.
* Don't give a Notify entry a name starting with `ns_chat` or `NS_Chat`, or a `notification` value containing `"type": "ns_chat"`: those mark it as a NetSapiens Chat Notification instead.

> [!TIP]
>
> To email a summary after every call, you don't need a function: set `email` (and optionally `sendRecordingLinkWithSummary`) on [Update Agent](https://docs.telzino.com/api-reference/agents/update.md).

## Example: add Send SMS via Twilio

1. Read the agent:

   ```bash theme={null}
   curl https://api.telzino.com/v1/agents/AGENT_ID \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   ```

2. Copy `extensions` from the response, add the Send SMS entry to `extensions.tools`, and send it back:

   ```bash theme={null}
   curl -X PUT https://api.telzino.com/v1/agents/AGENT_ID \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "extensions": {
         "tools": [
           { "...": "the agent'\''s existing tools, unchanged" },
           {
             "name": "send_sms_via_twilio",
             "type": "twilio_sms",
             "friendlyName": "Send_SMS",
             "condition": "during_call",
             "url": "internal://twilio-sms-service",
             "method": "POST",
             "headers": [{ "key": "Content-Type", "value": "application/json" }],
             "description": "When a caller books an appointment, text them the date, time and address.",
             "parameters": [
               { "key": "sms_instructions", "value": "When a caller books an appointment, text them the date, time and address." },
               { "key": "from_number", "value": "+15555550100" }
             ]
           }
         ]
       }
     }'
   ```

   Replace the placeholder line with the agent's real existing entries, and keep the other keys from `extensions`. MCP connections come back from Get Agent in their stored shape, so convert them to the request shape before sending them back. See [Get Agent: Stored MCP Connection Shape](https://docs.telzino.com/api-reference/agents/get.md#stored-mcp-connection-shape).

3. Read the agent again to confirm the entry was saved. The change appears in [Change History](https://docs.telzino.com/api-reference/agents/history.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.