<!-- VanceTel docs · /docs/deep-links -->

# Deep links

Deep links are URLs that open the softphone with an action ready to go — a call to a number, or a new text addressed to a recipient. Drop them on any button, CRM record or dashboard so your team can start a conversation in one tap, without copying numbers by hand.

Unlike the REST API, deep links don't send anything on their own. They hand off to the softphone app, which opens the dialer or composer pre-filled. The person still presses call or send.

  A deep link never sends anything by itself. A text link can pre-fill the **recipient** and,
  optionally, a **draft message body** — but that draft opens in the composer, editable, and is
  **never auto-sent**. The user reviews and taps Send. To send a message programmatically, use the
  [Send an SMS](/developers/docs/sms) endpoint instead.

## Format

```text
netexem://<action>?to=<E.164>[&from=<E.164>][&ad=<0|1>][&body=<encoded text>]
```

| Param  | Required | Notes |
|--------|----------|-------|
| `to`   | yes | Recipient in [E.164](/developers/glossary/e164). URL-encode the `+` as `%2B`. |
| `from` | no | For `sms`, selects which of your numbers to send from; defaults to your default line. For `call` it is parsed but ignored today. |
| `ad`   | no — `call` only | `1` auto-dials immediately; `0`/absent shows a confirmation prompt (the safer default). |
| `body` | no — `sms` only | URL-encoded draft message (soft cap ~1000 chars). Pre-fills the composer, editable, never auto-sent. Ignored on `call`. |

The only valid actions are `call` and `sms`. Any unknown action or malformed `to` is silently dropped (fails safe).

## Launch a call

A call deep link opens the softphone dialer with the recipient set, ready to dial. The number uses [E.164 format](/developers/glossary/e164).

```text
netexem://call?to=+15557654321
```

Use this on a "Call" button next to any phone number. The user taps, the dialer opens pre-addressed, and they press call.

## Launch a pre-addressed text

A text deep link uses the `sms` action and opens the message composer addressed to the recipient. With just `to`, the message field is left empty for the user to type.

```text
netexem://sms?to=+15557654321
```

## Pre-fill a draft message

Add an optional `body` parameter to pre-fill the composer with draft text. The user still reviews, edits and taps Send — nothing is auto-sent.

```text
netexem://sms?to=+15557654321&body=Hi%20there%2C%20your%20order%20%23123%20is%20ready
```

URL-encode the body with `encodeURIComponent` (JS) or `urllib.parse.quote` (Python): space → `%20`, newline → `%0A`, `&` → `%26`, `#` → `%23`. The body is a soft `~1000`-character cap (longer text is truncated) and is **ignored on `call`** links.

  `body` only applies to the `sms` action and only pre-fills the composer — it is never auto-sent.
  To send a message without a human in the loop, use the [Send an SMS](/developers/docs/sms) endpoint.

## Use cases

Deep links shine anywhere a human is about to start a conversation from your software:

- **CRM record** — render a call link next to each contact's number so a rep dials straight from the lead view.
- **Dashboard button** — add a "Text customer" button on an order or ticket that opens the composer addressed to them.
- **Support tool** — let an agent jump from a help-desk ticket into a call without retyping the number.

These pair naturally with [Contacts](/developers/docs/contacts): create the contact so the softphone resolves caller ID, then deep-link the call or text to that person's number.

## Building a link in your app

Construct the URL with the recipient as the `to` query parameter. URL-encode the value so the leading `+` survives.

**Node**

```ts
function callLink(to) {
  return `netexem://call?to=${encodeURIComponent(to)}`;
}

// body is optional — omit it to open an empty composer
function textLink(to, body) {
  const draft = body ? `&body=${encodeURIComponent(body)}` : "";
  return `netexem://sms?to=${encodeURIComponent(to)}${draft}`;
}

textLink("+15557654321", "Hi there, your order #123 is ready");
// netexem://sms?to=%2B15557654321&body=Hi%20there%2C%20your%20order%20%23123%20is%20ready
```

**Python**

```python
from urllib.parse import quote

def call_link(to: str) -> str:
    return f"netexem://call?to={quote(to)}"

# body is optional — omit it to open an empty composer
def text_link(to: str, body: str | None = None) -> str:
    draft = f"&body={quote(body)}" if body else ""
    return f"netexem://sms?to={quote(to)}{draft}"

text_link("+15557654321", "Hi there, your order #123 is ready")
# netexem://sms?to=%2B15557654321&body=Hi%20there%2C%20your%20order%20%23123%20is%20ready
```

Render the result as an ordinary anchor in your UI:

```html
<a href="netexem://call?to=+15557654321">Call Jane</a>
<a href="netexem://sms?to=+15557654321">Text Jane</a>
<a href="netexem://sms?to=+15557654321&body=Hi%20Jane">Text Jane (with draft)</a>
```

## Next steps

- [Contacts](/developers/docs/contacts) — create a contact so caller ID resolves
- [Send an SMS](/developers/docs/sms) — send a message programmatically, body and all
- [API reference](/developers/docs/api-reference) — every endpoint, with a live console