# Get a phone number

URL: /systems/communications/get-a-phone-number · Id: `guide:get-a-phone-number`

> Say "get a phone number for the business" and get a local number your agent answers, with texts, transcripts and a handoff to you.

Get a local number for the [Startup](/business/nouns/startup): customers call and text it, a voice agent answers, and the hard calls reach a person.

Needs: [Startup](/business/nouns/startup)

**Before it runs**

- You leave the chat: Never: it all happens in the chat.

## What you get
- 1 local number, held by your Company (Channel)
- 1 voice agent that answers, says it is an agent, and hands off to a person (Role)
- 1 transcript of every call, filed against the caller (Message)
- 1 carrier registration for business texting (Task)

## Your agent does
**For agents**

- Guide: `guide:get-a-phone-number`, status `beta`. Page: [/systems/communications/get-a-phone-number.md](/systems/communications/get-a-phone-number.md).
- Approval: none. Run it when the founder asks.
- Leaves the chat: never.
- Needs first: [Startup](/business/nouns/startup).
- Run: call the steps in order, each through the API, SDK, CLI or MCP tab below; a later step passes the `$id` an earlier one returns. Each value marked example is the sample business’s: pass the founder’s own.

| Step | Verb | Inputs (type, required, this guide’s value) | Returns |
| --- | --- | --- | --- |
| 1 | [`Channel.create`](/business/nouns/channel/create) (`verb:Channel.create`) | `medium` string, required: example `"sms"`; `areaCode` string: example `"512"` | `channel` Channel |

Returns: the last call answers with `channel` and its `action`, whose `status` is `done`, `pending` (waiting on an Approval or a Worker), `failed`, `canceled` or `refused`:

```json
{
  "api": "https://api.sb/leaseline.app",
  "channel": {
    "$id": "https://api.sb/leaseline.app/channels/channel_1",
    "$type": "Channel",
    "medium": "sms",
    "areaCode": "512"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/action_1",
    "operation": "Channel.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/action_1"
  }
}
```

Next: offer “Forward calls to my cell after hours”, or “Have the agent answer and book appointments”.

Calls: `Channel.create`

Ask:

```text
Get a phone number for the business.
Get me a local number in the 512 area code.
Set up a line customers can call and text.
```

API:

```bash
# Channel.create
curl -X POST https://api.sb/leaseline.app/channels \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"medium":"sms","areaCode":"512"}'
```

SDK:

```ts
import { $ } from 'startup-builder'

await $.Channel.create({ medium: 'sms', areaCode: '512' })
```

CLI:

```bash
npx startup-builder do Channel.create --json '{"medium":"sms","areaCode":"512"}'
```

MCP:

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Channel.create({ medium: 'sms', areaCode: '512' })"
  }
}
```

## Change it
- Forward calls to my cell after hours.
- Have the agent answer and book appointments.
- Text customers when their order ships.
- Port the number we already have.

## Under the hood
- Systems: [Phone](/systems/phone), [Support](/systems/support), [Notices](/systems/notices)
- Nouns: [Channel](/business/nouns/channel), [Message](/business/nouns/message), [Conversation](/business/nouns/conversation)
- Events: `Channel.created`

The number is an `sms` [Channel](/business/nouns/channel) in [Phone](/systems/phone), and it takes calls too.

Calls ring the voice agent first. A caller who asks for a person, or a question it cannot answer, transfers through [`Conversation.escalate`](/business/nouns/conversation/escalate) with the transcript attached. Texting customers at volume starts once carriers approve the Startup's registration.