Texting and inbox

Read calls, voicemails, and texts in one history. Send from a business number, check delivery, and share reusable replies with your team.

The activity model

Messages use shared persistence (messages and message_send_attempts), rather than separate SMS and MMS tables. A message retains its identity across retries; each provider submission has its own potentially chargeable attempt. Currently only SMS is implemented. Sending uses /business_numbers/:id/messages, retrieval uses /messages/:id, and explicit retries use /messages/:message_id/retries. The unused proof-of-concept /business_numbers/:id/sms_messages sending route is not exposed. The optional send body format defaults to sms; MMS is rejected before any provider request. Message activity uses type: "message" with a separate format: "sms". Future formats share the same message activity type.

List grouped previews with GET /api/v1/inbox, load a number's timeline with GET /api/v1/inbox/:phone_number/activity, and mark observed items seen with POST /api/v1/inbox/:phone_number/seen. The existing /api/v1/activity/unseen endpoint includes people with unseen incoming SMS when messaging is enabled.

Messages create or update the external phone number's contact touchpoint, advancing last_contact_at like calls and voicemails. Web and API inbox aggregation includes calls and voicemails, plus messages when the company's messaging feature flag is enabled. The web timeline renders enabled message activity alongside calls and voicemails through a shared message view. With messaging disabled, messages are excluded from timelines, previews, unseen counts, and seen updates. Unknown activity types are skipped by the web renderer. The inbox API derives message ordering directly from message timestamps.

A conversation is a grouped view of activity for a company and external phone number. There is no conversation resource to create, no conversation ID, and no requirement to save a named contact before texting. Business-number filters narrow that view without changing the underlying records.

Use the existing contacts API for recipient details and the caller context API for integration panels. Every endpoint below accepts company API keys or OAuth tokens. Sending and retrying additionally require a current employee belonging to that company.

Properties

Inbox threads include phone_number, a nullable contact reference, last_activity_at, unseen_count, business_number_ids, reply_business_number_id, preview, and latest_item. The preview is limited to 160 characters. The latest-item metadata omits full text, summary, transcript, and recording URL; load activity for the full content. The suggested reply number is the latest item's number when it supports sending, otherwise null. Always select the sender explicitly for a send.

Thread unseen counts include only incoming calls, voicemails, and incoming texts with no seen timestamp. Outgoing activity never contributes to unread counts, even if its seen timestamp is cleared. A voicemail and its linked missed call count as one item. The existing unseen activity API counts distinct people per business number rather than summing message counts. The unread endpoint includes incoming SMS when messaging is enabled. The legacy /calls/seen endpoint remains calls-and-voicemails-only; use the inbox seen endpoint to acknowledge SMS. Clients should ignore unknown activity types and continue cursor pagination even when a page contains only unsupported items. A whole-thread seen acknowledgement applies to every activity type through its observation boundary, including items a client did not render.

Messaging capabilities

Read messaging from the business-number API:

{
  "messaging": {
    "sms": { "can_send": true, "can_receive": true },
    "mms": { "can_send": false, "can_receive": false }
  }
}

The company's messaging feature flag defaults to off and is managed by Phone.inc. Messaging endpoints (messages, retries, text snippets, and texting settings) return 404 while it is off. SMS is excluded from inbox previews, timelines, unseen counts, and seen updates. Sending capabilities also require this flag, including queued sends, retries, and automatic replies. Receive capability reflects the number's provider and inventory: signed carrier callbacks keep storing inbound messages and updating delivery state even with messaging off, so messages become visible when it is enabled. The number's existing provider handles voice and messaging. Currently only inMobile SMS is implemented; MMS is advertised as unsupported.

Unsupported or inactive senders cannot send, retry, or dispatch queued attempts. Existing history remains available when the company's messaging flag is enabled; delivery callbacks continue regardless of that flag. The message endpoints are format-neutral; only SMS is currently implemented. Automatic replies remain SMS-only.

Delivery, retries, and live updates

Send with the existing Send an SMS endpoint. Use a new idempotency key for each intentional send and reuse that key after a transport interruption. Keys are scoped to the sender business number. Reusing a key with changed recipient, body, or employee returns 409.

Messages are persisted before the provider request. A send error after persistence includes the stable message id. Check that record before taking further action. There are no automatic provider-request retries. A process interrupted after claiming an attempt leaves its state unknown, not safely retryable.

Incoming messages and delivery callbacks use signature verification. Incoming provider message IDs are deduplicated permanently while their SMS record exists, independently of receipt retention. Provider timestamps do not control the arrival/seen boundary. Texts and settings are not governed by call-data retention; they remain until their owning number or company is removed.

The authenticated CallsChannel sends sms_update notifications containing id and phone_number, plus unseen_update notifications. Treat these as invalidations: refresh the inbox, activity, or message endpoint. Refresh on reconnect as well. No message body is broadcast. Mobile background notification registration and delivery are not part of this API.

Incoming callbacks persist texts only for active inMobile business numbers. Callbacks for unknown or non-active numbers are rejected before reserving a receipt or enqueueing an auto-reply.

Canonical inMobile webhooks are /webhooks/inmobile/messages for incoming messages and /webhooks/inmobile/delivery_reports for outgoing delivery reports. The existing /webhooks/inmobile/sms and /webhooks/inmobile/sms_statuses URLs remain direct aliases, so existing provider configuration and preview callback URLs keep working.

For delivery callbacks, configure the server-owned INMOBILE_SMS_STATUS_CALLBACK_URL to your public /webhooks/inmobile/sms_statuses URL and configure InMobile signing keys through INMOBILE_WEBHOOK_PUBLIC_KEYS. The URL is attached to outgoing provider requests; clients cannot override it. Without a callback configuration, accepted messages cannot advance to confirmed delivery through this integration.

List the inbox

curl --get https://app.phone.inc/api/v1/inbox \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  --data-urlencode 'limit=50'

{
  "threads": [
    {
      "phone_number": "+4523909778",
      "contact": null,
      "last_activity_at": "2026-10-06T10:41:00.000000Z",
      "unseen_count": 1,
      "business_number_ids": [
        "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01"
      ],
      "reply_business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
      "preview": "Is the basket included?",
      "latest_item": {
        "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc",
        "type": "message",
        "format": "sms",
        "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
        "direction": "inbound",
        "status": "received"
      }
    }
  ],
  "next_cursor": null
}

List activity

curl --get https://app.phone.inc/api/v1/inbox/%2B4523909778/activity \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  --data-urlencode 'limit=50'

{
  "phone_number": "+4523909778",
  "contact": null,
  "items": [],
  "next_cursor": null,
  "observed_at": "2026-10-06T10:41:00.000000Z"
}

Mark activity seen

curl -X POST https://app.phone.inc/api/v1/inbox/%2B4523909778/seen \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"through":"2026-10-06T10:41:00.000000Z"}'

Retrieve a text

curl https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

{
  "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc",
  "type": "message",
  "format": "sms",
  "created_at": "2026-10-06T10:41:00.000000Z",
  "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "business_number_name": "Sales",
  "seen_at": "2026-10-06T10:41:00.000000Z",
  "direction": "outbound",
  "from": "+4592450113",
  "to": "+4523909778",
  "text": "Your appointment is confirmed.",
  "author": {
    "type": "employee",
    "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
    "name": "Lea"
  },
  "status": "accepted",
  "sms_count": 1,
  "encoding": "gsm7",
  "delivered_at": null,
  "received_at": null,
  "failure_code": null,
  "can_retry": false
}

Retry a failed text

curl -X POST https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc/retries \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"retry-appointment-1"}'

{
  "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc",
  "type": "message",
  "format": "sms",
  "status": "accepted",
  "can_retry": false
}

List snippets

curl https://app.phone.inc/api/v1/text_snippets \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

[
  {
    "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
    "title": "On my way",
    "text": "I'm on my way, with you in about 15 minutes.",
    "position": 0,
    "created_at": "2026-10-06T10:41:00.000000Z",
    "updated_at": "2026-10-06T10:41:00.000000Z"
  }
]

Create a snippet

curl -X POST https://app.phone.inc/api/v1/text_snippets \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"On my way","text":"I'"'"'m on my way, with you in about 15 minutes.","position":0}'

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "title": "On my way",
  "text": "I'm on my way, with you in about 15 minutes.",
  "position": 0,
  "created_at": "2026-10-06T10:41:00.000000Z",
  "updated_at": "2026-10-06T10:41:00.000000Z"
}

Retrieve a snippet

curl https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "title": "On my way",
  "text": "I'm on my way, with you in about 15 minutes.",
  "position": 0,
  "created_at": "2026-10-06T10:41:00.000000Z",
  "updated_at": "2026-10-06T10:41:00.000000Z"
}

Update a snippet

curl -X PATCH https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"I'"'"'ll be there in 10 minutes."}'

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "title": "On my way",
  "text": "I'll be there in 10 minutes.",
  "position": 0,
  "created_at": "2026-10-06T10:41:00.000000Z",
  "updated_at": "2026-10-06T10:42:00.000000Z"
}

Delete a snippet

curl -X DELETE https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Retrieve texting settings

curl https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

{
  "auto_reply_enabled": false,
  "auto_reply_text": null,
  "auto_reply_cooldown_minutes": 1440
}

Update texting settings

curl -X PATCH https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_reply_enabled":true,"auto_reply_text":"We'"'"'re closed now. We'"'"'ll reply when we reopen.","auto_reply_cooldown_minutes":1440}'

{
  "auto_reply_enabled": true,
  "auto_reply_text": "We're closed now. We'll reply when we reopen.",
  "auto_reply_cooldown_minutes": 1440
}