Phone Contact Rules

Phone rules attach to the agent identity and cover incoming and outgoing SMS/MMS, calls, and iMessage. For a shared policy, set phone_filter_mode and omit rule direction: new rules apply to both sending and receiving. Standalone number rules and contact permission edits change the same choices. An active exact-number allow or block takes precedence in either mode. Numbers without an applicable exact choice follow the direction’s mode:

phone_filter_mode: "whitelist": unmatched numbers are denied.
phone_filter_mode: "blacklist": unmatched numbers are permitted.

Set phone_filter_mode on the identity via PATCH /identities/{agent_handle} for both directions. Use phone_inbound_filter_mode and phone_outbound_filter_mode for independent defaults. Inbound is from the external party to the agent; outbound is from the agent to that party. Only rules covering that direction apply. Rules match exact E.164 phone numbers (match_type: "exact_number"). See Manage identities. New directional SDK/CLI options require 0.7.3 or later.

Existing-call transfers and guests

During an existing Voice AI call on a dedicated phone or dedicated iMessage line, a transfer destination or conference guest does not need allowlist membership. An applicable explicit outbound block still prevents the connection. Starting a separate outbound call still follows the identity’s outbound filter mode. Shared iMessage lines cannot transfer calls or add guests. See Voice AI transfers and group calls.

Direction and rule identity

Companion mode can permit a sponsored group MMS conversation without globally allowing its participants. An applicable block on any participant still vetoes Companion permission in that direction. New voice calls and separate private texts remain governed by ordinary rules; group replies still require consent and a ready sender. Activation eligibility requires active exact_number allows covering inbound and outbound for the actual sending number. One both allow or separate one-way allows qualify. Blacklist defaults and contact visibility do not. These rules also determine iMessage sender eligibility, while each channel keeps its resource and group-readiness requirements.

Create defaults to direction: "both". PATCH without direction preserves coverage.
List filters inbound and outbound include both rules. The both filter selects only bidirectional rules. Omit direction for all rules without duplicates. Action and match-type filters apply independently before pagination. A2A filters remain exact matches with their existing defaults.
Compatible new coverage for one number widens the existing rule to both. Matching actions and lifecycle states consolidate on creation or later edits. Previously issued IDs still support get, update, and delete of the consolidated logical rule; lists include it once. IDs do not permanently denote their original direction.
POST returns 201 for insertion or widening. Use the returned ID and direction rather than assuming a new ID. PATCH returns 200.
Duplicate coverage returns 409 with rule_already_exists and existing_rule_id. Conflicting actions also return 409; create does not overwrite them. Paused coverage is not silently reactivated or combined with active coverage.
A both rule has one action. Use separate one-way rules for opposing actions. Receiving permission does not grant permission to reply, and sending permission does not replace consent or channel-readiness requirements.

The deprecated per-number routes retain these same semantics. Shared-line iMessage setup additionally requires both effective permissions. When a caller or sender is blocked: inbound calls are rejected before they connect, and inbound texts are stored but never delivered to the agent. No text.received webhooks fire, identity-scoped keys never see the blocked rows, and admin API keys or the Inkbox Console can audit them with is_blocked=true filters on the calls and texts listings. Phone permissions can be configured without a dedicated phone number. phone_filter_mode and imessage_filter_mode are aliases; conflicting values in one request return 422. Releasing or replacing a number preserves the identity’s permissions. Actual sends and calls still require a ready channel.

Deprecated. The per-number routes under /numbers/{phone_number_id}/contact-rules are deprecated. Use the handle-keyed routes documented below instead.

Auth. Claimed agent keys can read their permitted rules. Creating, updating, or deleting rules requires an admin API key or the Inkbox Console. Agent writes return 403. Org-wide listings require administrative access.

List contact rules

GET /identities/{agent_handle}/phone-contact-rules

List contact rules for an agent identity, newest first, including identities without a dedicated phone number. An identity-scoped API key may read only its own identity’s agent_handle. Another handle returns 403; agent keys cannot create rules.

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle, with or without the leading `@`

Query parameters

Parameter	Type	Default	Description
`action`	string	—	Filter by `"allow"` or `"block"`
`direction`	string	All	`"inbound"` or `"outbound"` includes `"both"`; `"both"` is exact
`match_type`	string	—	Filter by match type (`"exact_number"` is the only value in v1)
`limit`	integer	50	1–200
`offset`	integer	0	Offset for pagination

Response (200)

JSON

[
  {
    "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "action": "block",
    "direction": "both",
    "match_type": "exact_number",
    "match_target": "+14155550100",
    "status": "active",
    "created_at": "2026-04-21T12:30:00Z",
    "updated_at": "2026-04-21T12:30:00Z"
  }
]

Code examples

curl "https://inkbox.ai/api/v1/identities/my-agent/phone-contact-rules" \
  -H "X-API-Key: YOUR_API_KEY"

rules = inkbox.phone_identity_contact_rules.list("my-agent")
for rule in rules:
    print(rule.action, rule.match_target, rule.status)

const rules = await inkbox.phoneIdentityContactRules.list("my-agent");
for (const rule of rules) {
  console.log(rule.action, rule.matchTarget, rule.status);
}

Create contact rule

POST /identities/{agent_handle}/phone-contact-rules

Add an allow or block rule for an agent identity. New rules are always created active.

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle

Request body

Field	Type	Required	Description
`action`	string	Yes	`"allow"` or `"block"`
`match_target`	string	Yes	E.164 phone number to match (e.g. `+14155550100`)
`match_type`	string	No	Defaults to `"exact_number"` (the only value in v1)
`direction`	string	No	`"inbound"`, `"outbound"`, or `"both"` (default); null is invalid

Request example

JSON

{
  "action": "block",
  "match_target": "+14155550100"
}

Response (201)

Returns the saved rule, which may be an existing rule widened to both. See Contact rule object.

Error responses

Status	Description
403	Creating rules requires an admin API key or the Inkbox Console; agent keys cannot create rules for any identity
404	Identity not found, or not visible to the caller
409	Duplicate coverage (`rule_already_exists`, including `existing_rule_id`) or conflicting coverage for the same number
422	Invalid `action`, `match_type`, or `match_target`

Code examples

curl -X POST "https://inkbox.ai/api/v1/identities/my-agent/phone-contact-rules" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "block", "match_target": "+14155550100"}'

rule = inkbox.phone_identity_contact_rules.create(
    "my-agent",
    action="block",
    match_target="+14155550100",
)

const rule = await inkbox.phoneIdentityContactRules.create("my-agent", {
  action: "block",
  matchTarget: "+14155550100",
});

Get contact rule

GET /identities/{agent_handle}/phone-contact-rules/{rule_id}

Fetch a single rule by ID.

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle
`rule_id`	UUID	Rule ID

Response (200)

Returns the rule. See Contact rule object.

Error responses

Status	Description
403	Identity-scoped key addressed a different identity’s handle
404	Rule not found or it belongs to a different identity

Update contact rule

PATCH /identities/{agent_handle}/phone-contact-rules/{rule_id}

Change a rule’s action or coverage, or atomically edit one covered side. Requires an admin API key, or manage rules from the Inkbox Console. match_type and match_target are immutable; delete the rule and create a new one to change the target.

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle
`rule_id`	UUID	Rule ID

Request body

Supply action, direction, or both. apply_to requires action and excludes direction. Supplied values cannot be null.

Field	Type	Required	Description
`action`	string	Conditional	`"allow"` or `"block"`; required with `apply_to`
`direction`	string	No	`"inbound"`, `"outbound"`, or `"both"`; changes coverage
`apply_to`	string	No	`"inbound"` or `"outbound"`; change only that covered side’s action atomically

Request example

JSON

{
  "action": "allow"
}

Response (200)

Returns the updated rule. Use {"action":"block","apply_to":"inbound"} on a both allow to block inbound while preserving outbound allow. The response contains the addressed inbound rule; refresh the list to see the preserved outbound rule. Applying the current action does not split the rule. By contrast, {"direction":"inbound"} removes outbound coverage; the remaining rules and outbound default decide sending permission. An action-only PATCH changes every direction the rule currently covers.

updated = inkbox.phone_identity_contact_rules.update(
    "my-agent", rule_id, action="block", apply_to="inbound",
)

import { PhoneRuleAction } from "@inkbox/sdk";

const updated = await inkbox.phoneIdentityContactRules.update("my-agent", ruleId, {
  action: PhoneRuleAction.BLOCK, applyTo: "inbound",
});

inkbox identity phone-rules update my-agent RULE_ID --action block --apply-to inbound
inkbox identity phone-rules list my-agent --direction outbound

Error responses

Status	Description
403	Caller is not admin-scoped
404	Rule not found or it belongs to a different identity
409	The requested coverage conflicts with another rule
422	Empty update, null or invalid value, or `apply_to` without action, with direction, set to `both`, or selecting an uncovered side

Delete contact rule

DELETE /identities/{agent_handle}/phone-contact-rules/{rule_id}

Delete a rule. Requires an admin API key, or manage rules from the Inkbox Console.

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle
`rule_id`	UUID	Rule ID

Response (204)

No content.

Error responses

Status	Description
403	Caller is not admin-scoped
404	Rule not found or it belongs to a different identity

List org phone contact rules

GET /phone/contact-rules

Org-wide aggregate list of phone contact rules across every identity. Intended for admin dashboards that render rules org-wide without fanning out one request per identity. Requires an admin API key, or browse rules in the Inkbox Console. Results are grouped by matched contact ID, with rules that have no matched contact last. Within each group, rules are ordered by created_at descending and then id ascending. Grouping happens before pagination, and a contact’s rows can span adjacent pages.

Query parameters

Parameter	Type	Default	Description
`agent_identity_id`	UUID	—	Narrow to one identity by ID; omit to list across every identity in the org
`direction`	string	All	`"inbound"` or `"outbound"` includes `"both"`; `"both"` is exact
`action`	string	—	Filter by `"allow"` or `"block"`
`match_type`	string	—	Filter by match type (`"exact_number"` is the only value in v1)
`limit`	integer	50	1–200
`offset`	integer	0	Offset for pagination

Response (200)

Returns a list[ContactRule] grouped by contact, with the same object shape as the per-identity list.

Code examples

curl "https://inkbox.ai/api/v1/phone/contact-rules?action=block&limit=100" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY"

rules = inkbox.phone_identity_contact_rules.list_all(action="block")

const rules = await inkbox.phoneIdentityContactRules.listAll({ action: "block" });

Contact rule object

List, get, create, update, and organization-wide list responses include a nullable contact card for an exact target with one resolved owner in the rule’s organization. The card follows the caller’s contact permissions and contains no memories, memory_count, or latest_memory. Unresolved, ambiguous, and inaccessible matches return null. Reads resolve the current contact. An idempotent write replay preserves its original response snapshot. SDK/CLI 0.6.11 supports these cards; CLI tables show contact names and JSON output preserves the card.

Field	Type	Description
`contact`	object or null	Authorized matching contact card, without memories
`id`	string (UUID)	Rule ID
`agent_identity_id`	string (UUID)	The identity this rule protects
`action`	string	`"allow"` or `"block"`
`direction`	string	`"inbound"`, `"outbound"`, or `"both"`
`match_type`	string	`"exact_number"` (the only value in v1)
`match_target`	string	The matched phone number in E.164 format
`status`	string	`"active"`; existing rules may return `"paused"` as a read-only compatibility value. Status cannot be changed through PATCH.
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Additional resources

Phone guide — Filtering inbound calls and texts — narrative walk-through of whitelist/blacklist semantics
Manage identities — set phone_filter_mode
iMessage contact rules: alternative routes for the same phone communication list
Mail contact rules — the mail-side equivalent

​Existing-call transfers and guests

​Direction and rule identity

​List contact rules

​Path parameters

​Query parameters

​Response (200)

​Code examples

​Create contact rule

​Path parameters

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​Get contact rule

​Path parameters

​Response (200)

​Error responses

​Update contact rule

​Path parameters

​Request body

​Request example

​Response (200)

​Error responses

​Delete contact rule

​Path parameters

​Response (204)

​Error responses

​List org phone contact rules

​Query parameters

​Response (200)

​Code examples

​Contact rule object

​Additional resources

Existing-call transfers and guests

Direction and rule identity

List contact rules

Path parameters

Query parameters

Response (200)

Code examples

Create contact rule

Path parameters

Request body

Request example

Response (201)

Error responses

Code examples

Get contact rule

Path parameters

Response (200)

Error responses

Update contact rule

Path parameters

Request body

Request example

Response (200)

Error responses

Delete contact rule

Path parameters

Response (204)

Error responses

List org phone contact rules

Query parameters

Response (200)

Code examples

Contact rule object

Additional resources