# Set up Inkbox

Step by step, connect a bot to your Inkbox account, choose who may reach it, connect your phone for iMessage, and check it in Machine Desktop.

Canonical page: https://themachine.myapps.ai/docs/desktop/inkbox/set-up

This takes about ten minutes. You'll use the Inkbox Console, the Machine web
app, and your phone.

## Before you start

You need:

- **An [Inkbox](https://inkbox.ai) account** with an **agent**. Every Inkbox
  agent has a handle, such as `@scout`, and a mailbox, such as
  `scout@inkboxmail.com`.
- **An Inkbox API key.** An admin key works, and so does a key for just that
  one agent.
- **The phone numbers and email addresses** that may reach the bot.
- A Machine bot you can change.

You **don't need a phone number**. iMessage and voice calls work through
Inkbox's shared iMessage line, and email through the bot's Inkbox mailbox, all
on Inkbox's free plan. A number of the
bot's own (Inkbox Console → **Phone**) is optional: it adds SMS from any phone
(Android too), calls to and from any phone, and one number to hand out.

> **Keep the key out of chats**
> Paste your Inkbox key only into the Machine settings form below. Never send it
> to a bot in a message.

## Step by step

### Create an Inkbox agent and key

In the [Inkbox Console](https://inkbox.ai/console), create an agent if you
don't have one. Then open **API Keys**, create a key, and copy it. Inkbox
shows it only once.

### Open the bot's Channels in Machine Desktop

Open the bot's settings (click the bot's name at the top of the chat) and
open **Channels**. The Inkbox row says **Not connected**.

![Inkbox not connected yet. Connect opens the Machine web app](/images/docs/desktop/inkbox-not-connected.webp)

### Click Connect

Click **Connect ↗** on the Inkbox row. Your browser opens this bot's
**Channels** page on the Machine web app. Sign in if asked.

### Connect your Inkbox key

On the web page, find the **Inkbox** card and click **Connect Inkbox**. Paste
your Inkbox API key and fill in who may reach the bot:

- **Phone:** numbers allowed to iMessage, text or call the bot, one per line,
with the country code: `+14155550100`.
- **Email:** addresses allowed to email the bot, such as `dana@northwind.co`,
or a whole domain written `@northwind.co`.

Leave a list empty to keep that one off, but fill in at least one. If your key
can see more than one Inkbox agent, pick the one this bot should be and click
**Connect Inkbox** again.

See [Who can reach your bot](/docs/desktop/inkbox/who-can-reach-your-bot)
before you add a whole domain.

### Connect your phone for iMessage

On the web app, click **Manage** on the Inkbox card. Under **Connect your
phone to text the agent**, it shows a short text to send once from each
allowed phone, for example *text `connect @scout` to +1 (650) 484-9720*. Tap
**Open in Messages** to draft it, or scan the QR code. Each number on your
list then shows **Connected** or **Not connected yet**.

Inkbox replies with the bot's contact card. Save it, so the bot shows up by
name in Messages. If the Inkbox agent had no photo, Machine gives it a mascot;
**Contact photo** in **Manage** lets you shuffle or remove it.

- **Email** needs no extra step. Just write to the bot's address.
- **SMS** works once the bot has a number of its own. No connect text is
needed. In the US, text **START** to the bot's number once, so it's allowed
to text you back.

If the bot has a number, the top of **Manage** shows it large, with **Text**
and **Call** buttons and a QR code to share. Without one, it says **No phone
number needed** and lists iMessage, voice calls and email as **Ready**.

### Check it in Machine Desktop

Back in Machine Desktop, click the **refresh** icon in **Channels**. The
Inkbox row now says **Connected** with the bot's handle, email address, and
phone number if it has one.

![Inkbox connected: the bot's handle, phone number and email](/images/docs/desktop/inkbox-connected.webp)

### Say hello

Text the bot from your phone: *"Hi! What can you do for me?"* It replies in a
moment. Your conversation also appears as a thread in the bot in Machine
Desktop.

## Choose which agent and model answer

On the web app, **Manage** on the Inkbox card lets you choose which of the
bot's agents answers texts, email and calls, and which AI model it uses. Left
on **Default**, it follows the bot's own settings.

## Change who can reach the bot

Open the web app's **Manage** on the Inkbox card (or click **Manage ↗** in
Machine Desktop, which opens it), edit the phone and email lists, and click
**Save**.

## Disconnect Inkbox

In Machine Desktop, click **Disconnect** on the Inkbox row and confirm:
*"Disconnect Inkbox from Scout? People there will stop reaching this bot."*

Machine stops listening for the bot's texts, emails and calls and deletes the
stored key. Your Inkbox account, agent, number and past messages are
unchanged. Past conversations stay as threads in the bot.

## Good to know

- **One Inkbox agent, one bot.** An Inkbox agent can be connected to one bot
  at a time. Use a separate Inkbox agent for each bot you want to text.
- **The key stays on Machine's servers.** The bot never sees it. Machine adds
  it when the bot sends a text or email.
- **Rotated your key?** Disconnect, then connect again with the new key.

The full technical reference, including limits and every setting on the web
app, is in [Inkbox: iMessage, SMS, email & calls](/docs/connect/inkbox).