| name | inkbox-sms-responder |
| description | Use when the user asks to send a text, reply to an SMS, or triage the agent's SMS conversations, including group chats. Covers per-conversation context, opt-in/opt-out gates, and the 10DLC carrier propagation window. |
Inkbox SMS responder
The Inkbox plugin gives this agent a working phone number under an agent identity. Use this skill whenever the user asks you to check, triage, or reply to SMS or MMS conversations, including group chats — short, conversational, opt-in-gated.
Tools
Enabled by default:
inkbox_list_text_conversations — start here for triage; includes group chats and returns conversation IDsinkbox_get_text_conversation — pull message history by conversationId or legacy remotePhoneNumberinkbox_send_sms — outbound by conversationId, one E.164 recipient, or a 2-8 recipient group
Opt-in — the user must enable these in your .opencode/plugins/inkbox.ts wrapper, then restart opencode:
inkbox_list_texts, inkbox_get_text — low-level access to individual messagesinkbox_mark_text_read, inkbox_mark_text_conversation_read — clear unread state
InkboxPlugin(input, { "tools": { "enable": ["inkbox_mark_text_conversation_read"] } })
(Enabling the "sms" group turns all four on at once.) inkbox_doctor reports which tools are currently enabled or disabled.
Workflow
-
Pull conversations. Call inkbox_list_text_conversations (defaults: limit: 25, newest-updated first, groups included). Each row shows id, participants, isGroup, remotePhoneNumber for 1:1, latestText, unreadCount, totalCount.
-
Pick a conversation to handle. Read the latest text in the row. If you need history, call inkbox_get_text_conversation with conversationId: row.id and a reasonable limit (50 is fine). Use remotePhoneNumber only for old 1:1 rows that do not have an ID.
-
Compose and send. Prefer inkbox_send_sms with conversationId when replying to an existing conversation, especially a group. For a new text, pass to as one E.164 number or a list of 2-8 E.164 numbers. Keep the tone conversational — SMS isn't email. Sends prompt for approval through opencode's permission system by default; the outbound.allowedRecipients and outbound.approval ("ask" | "allowlist" | "auto") plugin options control this.
-
Mark as handled if inkbox_mark_text_conversation_read is enabled: pass conversationId.
Calling someone on SMS
If someone in an SMS conversation should get a call, place it from your dedicated phone line — the same number the conversation is on — with inkbox_place_call and origination: "dedicated_number". Set it explicitly. (The shared iMessage line is only for people connected over iMessage.)
inkbox_place_call is opt-in (enable it — or the "calls" group — the same way as above). It takes toNumber, origination, and optionally clientWebsocketUrl; every call needs a call WebSocket (an audio bridge Inkbox connects to), supplied per call via clientWebsocketUrl or via the callWebsocketUrl plugin option / INKBOX_CALL_WEBSOCKET_URL.
Gates and errors
- Opt-in required. Recipients must have texted
START to one of your Inkbox numbers. If they haven't, inkbox_send_sms returns the plain-language error "Recipient has not opted in to SMS." Surface this to the user; do not try to bypass.
- Opt-out is final. If a recipient texted
STOP, sending returns "Recipient has opted out of SMS." Do not attempt to message them again on the same number.
- Carrier propagation window. Newly provisioned local numbers take ~10–15 min to propagate to carriers. During this window, sends return "Your Inkbox phone number is still propagating to carriers." Wait it out; don't retry tight-loop.
- Toll-free numbers cannot send SMS today. If the identity's phone is toll-free, sends will fail — recommend the user provision a local number instead.
- Rate cap. Roughly 15 outbound sends per number per 24h. The plugin surfaces this as a 409. Pause sending and wait.
- Group chats. When triaging a group, reply only to messages that clearly address this agent or ask it to act. Do not comment on every group message — if nothing warrants a reply, skip the thread and report that to the user.
SMS-specific style
- Short. Often a single sentence is right.
- Don't include subject lines, signatures, or links unless explicitly asked.
- One thought per message; if it needs multiple parts, send them as separate messages rather than a 1600-char wall.
What this skill does NOT cover
- Provisioning phone numbers (done outside this plugin, e.g. via the Inkbox dashboard or CLI).
- Org-level SMS opt-in registry writes (admin-only, customer-managed 10DLC campaigns only).
- Creating a group with more than 8 recipients; carrier group MMS caps are lower than email-style threads.
When you need more — raw Inkbox docs
If something here doesn't match what you're seeing, or you need API behavior this skill doesn't describe (field names, error codes, edge cases), go to the source:
Prefer fetching these over guessing.
