inkbox-ai/inkbox/inkbox-onboarding

Inkbox Onboarding

Use this skill after an API key exists. If the agent still needs an account or API key, use inkbox-agent-self-signup first.

Onboarding Process

1. Confirm which Inkbox API key and identity should be used. Never print, log,

or commit the key.

1. Inspect the authenticated principal and current identities before creating or

changing anything.

1. Check each requested channel independently. A working mailbox does not imply

that SMS, calls, or iMessage are ready.

1. Ask before provisioning a number, enabling a channel, changing inbound

routing, creating a webhook, or sending test traffic.

1. Complete any recipient-side connection or consent step.
2. Run one bounded test per requested channel and verify the resulting record or

reply instead of assuming an accepted request was delivered.

1. Choose an inbound strategy: polling for simple agents, signed webhooks for

event-driven agents, or both.

1. Offer recurring inbox and conversation triage only after the channels are

ready. Confirm cadence, channels, identities, and whether replies are allowed.

Readiness Checklist

Identity creation provisions a mailbox and tunnel together. A phone number is optional and must be local; do not request a toll-free number. New local numbers can remain pending while messaging registration completes, so inspect sms_status and wait for ready rather than retrying sends.

Router numbers and connection commands can change. Always retrieve the current iMessage triage details at runtime and present them exactly as returned.

CLI

Install the CLI and keep the key in the environment:

npm install -g @inkbox/cli
export INKBOX_API_KEY="ApiKey_..."

Inspect before mutating:

inkbox whoami --json
inkbox identity list
inkbox identity get support-agent --json

With the user's approval, enable or provision only the requested channels:

inkbox identity update support-agent --imessage-enabled true
inkbox number provision --handle support-agent --type local --state NY
inkbox imessage triage-number

After number provisioning, run inkbox identity get support-agent --json again and wait for smsStatus to become ready. Before texting a recipient, verify that the recipient has opted in:

inkbox sms-opt-in get +15551234567

Use --json when another program will consume the output. Sending email, text, iMessage, or a call creates real external traffic and requires confirmation.

Python SDK

import os
from inkbox import Inkbox
with Inkbox(api_key=os.environ["INKBOX_API_KEY"]) as inkbox:
    principal = inkbox.whoami()
    identities = inkbox.list_identities()
    identity = inkbox.get_identity("support-agent")
    print(principal.auth_type)
    print(identity.mailbox)
    print(identity.phone_number)
    print(identity.imessage_enabled)
    # Mutations require the user's approval.
    # identity.update(imessage_enabled=True)
    # identity.provision_phone_number(type="local", state="NY")
    triage = inkbox.imessages.get_triage_number()
    print(triage.number, triage.connect_command)

After provisioning a number, refresh the identity before checking readiness:

identity.refresh()
if identity.phone_number is not None:
    print(identity.phone_number.sms_status)

For channel-specific operations, continue with inkbox-python rather than guessing method names or response fields.

TypeScript SDK

import { Inkbox } from "@inkbox/sdk";
const inkbox = new Inkbox({ apiKey: process.env.INKBOX_API_KEY! });
const principal = await inkbox.whoami();
const identities = await inkbox.listIdentities();
const identity = await inkbox.getIdentity("support-agent");
console.log(principal.authType);
console.log(identity.mailbox);
console.log(identity.phoneNumber);
console.log(identity.imessageEnabled);
// Mutations require the user's approval.
// await identity.update({ imessageEnabled: true });
// await identity.provisionPhoneNumber({ type: "local", state: "NY" });
const triage = await inkbox.imessages.getTriageNumber();
console.log(triage.number, triage.connectCommand);

Refresh after provisioning before checking identity.phoneNumber?.smsStatus:

await identity.refresh();
console.log(identity.phoneNumber?.smsStatus);

For channel-specific operations, continue with inkbox-ts.

Direct API

The API uses the same key and returns snake_case JSON:

export INKBOX_API_KEY="ApiKey_..."
 
curl -sS https://inkbox.ai/api/v1/whoami \
  -H "X-API-Key: ${INKBOX_API_KEY}"
 
curl -sS https://inkbox.ai/api/v1/identities \
  -H "X-API-Key: ${INKBOX_API_KEY}"
 
curl -sS https://inkbox.ai/api/v1/identities/support-agent \
  -H "X-API-Key: ${INKBOX_API_KEY}"

These mutations require confirmation:

curl -sS -X PATCH https://inkbox.ai/api/v1/identities/support-agent \
  -H "X-API-Key: ${INKBOX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"imessage_enabled":true}'
 
curl -sS -X POST https://inkbox.ai/api/v1/phone/numbers \
  -H "X-API-Key: ${INKBOX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"agent_handle":"support-agent","type":"local","state":"NY"}'

Use the published OpenAPI document at https://inkbox.ai/api/openapi.json for complete request and response schemas.

Inbound Communications

Polling is the smallest setup for an agent that already runs on a schedule. List unread email and recent SMS, iMessage, calls, and A2A tasks; fetch only the bounded conversation context needed; then persist a cursor or last-success time so the next run does not reply twice.

Use webhooks when the agent needs prompt delivery. With SDK/CLI 0.7.8 or later and GET /webhooks/catalog advertising supports_identity_subscriptions: true, one identity-owned subscription can combine notification families even before optional channels are configured. Until then, keep separate subscriptions using mailbox selectors for mail, phone selectors for text, and identity selectors for identity events. Subscribe to only the event types and identities the agent needs, verify every signature against the raw request body, return quickly, and process idempotently. Use an Inkbox tunnel when the receiver runs locally; see inkbox-tunnels for setup and recovery.

Recurring Triage

When the client supports scheduling, offer a task with an explicit cadence and scope. A safe default instruction is:

Check unread email, new SMS and iMessage conversations, recent or missed calls,

and new or input-required A2A tasks since the last successful run. Read only

the context needed to understand each item. Reply only where the schedule

explicitly allows it, use the same channel, never respond twice, and report

sends that fail. Finish with actions taken, items needing a decision, and any

channel setup problems.

Do not create a schedule or authorize automatic replies without the user's approval.

Slack

After connecting, contact import is optional: it saves visible people without allowing messages or enabling Companion. In 0.7.14+, an organization admin can use slack contacts-import and slack contact-rule, or the corresponding SDK methods. Follow import cursors. Changing Slack whitelist/blacklist defaults on the identity also requires an organization admin key. Companion requires an exact human account allowed in both directions; a workspace allow alone does not sponsor access.

See the Slack API and onboarding guide for implemented SDK/CLI methods. Use an existing identity and select the intended connected workspace explicitly. Organization-member sessions, organization admin API keys, and claimed agent keys can save and list setup workspaces in their organization. Claimed agent keys can prepare and install only their own identity’s app; organization credentials can select an identity in their organization. Installation availability does not imply preparation is ready. Save both app-configuration tokens for the target workspace, then prepare the identity’s app using that saved provisioning-workspace UUID. Use save_provisioning_workspace / saveProvisioningWorkspace or CLI slack provisioning-workspace save --credentials-file <path> (use - for stdin). Reuse safe metadata from list_provisioning_workspaces / listProvisioningWorkspaces. Tokens are write-only; never put them in command arguments or output. Pass the saved ID to start_setup (Python/Rust), startSetup (TypeScript), or slack setup start --provisioning-workspace-id <uuid>. Poll connection reads until setup.status is ready, with a bounded wait and a few seconds between reads. For needs_credentials, select a saved workspace or save valid configuration credentials. Do not blindly retry an unknown setup outcome. Start installation only when ready. Open the returned URL in a browser; treat the full URL as a secret. After approval, list connections again to confirm the expected workspace is connected. The app is bound to its chosen workspace; no client-invitation workflow is supported. Join accessible public channels or invite the agent to selected private channels. Slack Connect is supported when the selected connection has access.

App removal (0.7.23+). For user-requested app removal, use an organization admin API key; claimed agent keys cannot remove apps or read removal status. Removal is not the default repair for a reauthorization error. Read the connection list and check application_created / applicationCreated before using its application generation. Generate a fresh request UUID once and save it with that generation before removal; retry uncertain requests with those same values, not a newly read generation. The removal operation ID equals its saved request UUID.

Use remove_application and get_application_removal (Python/Rust), removeApplication and getApplicationRemoval (TypeScript), or slack application remove --expected-application-generation <saved-generation> --request-id <saved-uuid> and slack application removal-status --operation-id <saved-uuid> (CLI). Generate the request UUID once, for example with uuidgen, before making the call.

Poll the saved operation ID every few seconds with a bounded wait while deletion is pending, including when the error is credentials_busy. failed and unknown are terminal; replay does not retry deletion. Removal always attempts permanent Slack-side deletion, but credential errors or timeouts do not prove the app is gone. If needed, check and delete the original app in Slack with its original creator. Removal never prepares another app. Previous connection history becomes unavailable; the Inkbox identity, other channels, and memory are unchanged. For a fresh app, select the intended saved workspace-and-creator record (or save another token pair), start setup explicitly, wait until ready, authorize installation, and invite the new bot back to channels. A retained non-null app generation does not mean an app exists.