Skip to content

Tools

The server registers 16 tools. Each one calls one SDK method with the server’s API key, so the key’s scopes decide which tools work. A tool the key can’t use returns SMSFabric error 403 (forbidden) to the assistant rather than failing silently.

Every tool answers with a one-line summary for the assistant, followed by the full JSON response. Errors come back as a tool error with the HTTP status, the code, the detail and any field errors, so the assistant can explain or fix the request.

Tool Scope Annotation
send_sms messages:send destructive (sends)
list_messages messages:read read-only
get_message messages:read read-only
send_verification verify:send sends
check_verification verify:check uses an attempt
list_devices devices:read read-only
find_contacts contacts:read read-only
add_contact contacts:manage writes
list_campaigns campaigns:read read-only
get_campaign campaigns:read read-only
create_campaign campaigns:manage writes a draft
estimate_campaign campaigns:read read-only
start_campaign campaigns:manage, messages:send destructive
pause_campaign campaigns:manage writes
resume_campaign campaigns:manage writes
cancel_campaign campaigns:manage destructive

Phone numbers are always E.164: a +, the country code and the number, 8 to 16 characters in all (+201001234567).

Sends SMS

Sends one text to one number or up to 100 through your gateway phones. A blacklisted number comes back with status blocked. With an sf_test_ key nothing reaches a real phone.

The tool is annotated readOnlyHint: false, destructiveHint: true and openWorldHint: true: a sent SMS can’t be recalled, so clients that honour annotations ask before every call. Its description tells the assistant to make up one idempotencyKey per message it means to send and to reuse that key if it calls send_sms again after a timeout or error. SMSFabric then returns the original messages instead of sending a second time.

Input Type Required Constraints
to string or string[] yes E.164, or a list of 1 to 100 E.164 numbers
body string yes 1 to 1,600 characters
deviceId string no Send from this phone (dev_…)
simId string no Send from this SIM (sim_…)
poolId string no Send through this pool (pool_…)
idempotencyKey string no 1 to 255 characters, unique per intended send. Reuse it when retrying the same send. Without it, only the client’s own automatic retries are protected

Returns one line per message (msg_… → +201001234567: queued) and the messages as JSON.

Example prompt: “Text +201001234567: Your table for 4 is ready at 8 pm.”

Lists recent messages, newest first.

Input Type Required Constraints
direction enum no outbound or inbound
status enum no queued, routed, sending, sent, delivered, failed, blocked, received
q string no Digits of a phone number: 3 to 15, with an optional leading +. Matches any part of to or from, so 4567 finds numbers ending in 4567. Names aren’t accepted; use find_contacts for those
limit integer no 1 to 200. Default 20
cursor string no The nextCursor from the previous call

Returns one line per message (time, direction, number, status and the first 80 characters) and the page as JSON, with nextCursor when there is more.

Example prompt: “Show me the messages that failed today.”

Gets one message with its delivery timeline.

Input Type Required Constraints
id string yes A message id, msg_ followed by lowercase letters and digits

Returns the status and the event chain (queued → routed → sent → delivered), then the message as JSON.

Example prompt: “Was msg_q8v2k4n6p1r3t5w7y9z0b2c4 delivered?”

Sends SMS

Sends a one-time code to check that someone controls a phone number. SMSFabric generates the code and never returns it; the assistant must ask the person to read it back. A new send to the same number replaces the pending code. At most 3 codes per number every 10 minutes, and the country must be allowed in the portal under Verify settings.

Input Type Required Constraints
to string yes E.164
locale enum no en or ar. Default en
codeLength integer no 4 to 10 digits. Default 6
ttlSeconds integer no 60 to 1,800. Default 600

Returns the verification id (ver_…), the masked number, its status and when it expires.

Example prompt: “Send a verification code in Arabic to +201001234567.”

Checks the code the person received. Every call uses one of the 5 attempts, so the assistant should only check a code the person gave it.

Input Type Required Constraints
id string yes The ver_… id from send_verification
code string yes 4 to 10 digits

Returns approved (the number is verified), pending with the attempts left (wrong code), denied (5 wrong codes) or expired.

Example prompt: “She says the code is 482913.”

Lists your gateway phones. It takes no input.

Returns one line per phone (id, name, online, offline or disabled, battery and number of SIMs) and the phones as JSON, with signal, network and SIM details.

Example prompt: “Are all our gateway phones online? Which ones are below 20% battery?”

Searches the address book.

Input Type Required Constraints
q string no Up to 120 characters. A name or email (contains), a full E.164 number, or its last 4 digits
tag string no Up to 40 characters
groupId string no grp_ followed by lowercase letters and digits
optedOut boolean no true: only opted-out contacts; false: only reachable ones
limit integer no 1 to 200. Default 20
cursor string no The nextCursor from the previous call

Returns one line per contact (id, number, name, tags and [opted out]) and the page as JSON.

Example prompt: “Find the contact whose number ends in 4567.”

Adds a contact, one per number. A number that already exists returns 409 contact_exists.

Input Type Required Constraints
phone string yes E.164
firstName string no Up to 120 characters
lastName string no Up to 120 characters
email string no A valid email, up to 254 characters
tags string[] no Up to 20 tags of up to 40 characters each
consentSource enum no Where the person agreed to receive messages: web_form, import, api, in_person, paper, sms_keyword (they texted a keyword such as START), other

Returns the new contact’s id and number, and the contact as JSON.

Example prompt: “Add Sara Adel, +201001234568, tagged vip. She signed up on our website.”

Campaign ids are cmp_ followed by lowercase letters and digits. A campaign runs draft → running ⇄ paused → completed, or ends canceled.

Lists campaigns, newest first, with progress.

Input Type Required Constraints
status enum no draft, scheduled, running, paused, completed, canceled
limit integer no 1 to 200. Default 20
cursor string no The nextCursor from the previous call

Returns one progress line per campaign: id, name, status, sent of recipients, delivered, failed, skipped, pending and the ETA.

Example prompt: “Which campaigns are running right now?”

One campaign with live progress, or its report.

Input Type Required Constraints
id string yes cmp_…
report boolean no true adds skips by reason, failures by error code and counts per phone

Returns the progress line, and with report the skip and failure breakdown, then the JSON.

Example prompt: “How did the November offers campaign do? Why were people skipped?”

Creates a draft. Nothing is sent until start_campaign. The audience is the contacts in any of the groups or with any of the tags. The body may use {{first_name}}, {{last_name}} and {{custom.<key>}}, with fallbacks such as {{first_name|there}}; the description asks the assistant to include opt-out wording such as “Reply STOP to opt out”.

Input Type Required Constraints
name string yes 1 to 120 characters
body string no 1 to 1,600 characters. Give exactly one of body and templateId
templateId string no tpl_ followed by lowercase letters and digits. Give exactly one of body and templateId
groupIds string[] no Up to 20 grp_… ids
tags string[] no Up to 20 tags of up to 40 characters each
poolId string no Send through this pool
ratePerMinute integer no 1 to 6,000 across all phones. Default 120
hourlyCap integer no 1 to 360,000 recipients per clock hour in the campaign time zone
dailyCap integer no 1 to 8,640,000 recipients per calendar day; not below hourlyCap
quietHoursStart string no HH:MM (24-hour) in each recipient’s local time, e.g. 21:00
quietHoursEnd string no HH:MM, e.g. 09:00
scheduledAt string no ISO 8601 date and time with an offset, e.g. 2026-12-01T09:00:00+02:00. start_campaign then schedules the campaign for that time instead of starting it now

Give quietHoursStart and quietHoursEnd together or not at all. The tool returns an error, without calling the API, when only one is given or when body and templateId are both given or both missing.

Returns the draft’s id with a reminder to estimate before starting, and the campaign as JSON.

Example prompt: “Draft a campaign called Weekend offer to the vip tag: Hi {{first_name|there}}, 20% off this weekend. Reply STOP to opt out. No messages between 9 pm and 9 am.”

What a draft or scheduled campaign will do before it starts: recipients after opt-outs and the blacklist, total segments, the effective rate given the throttle and phone capacity, how many recipients wait for quiet hours, the duration and any warnings.

Input Type Required Constraints
id string yes cmp_…

Returns a summary such as “1,240 recipients (12 opted out, 3 blacklisted skipped), 1,240 segments, about 11 min at 120/min” and the estimate as JSON.

Example prompt: “How long would that campaign take, and how many people would get it?”

Destructive

Starts a draft now, or at its scheduled time. It sends real SMS to every recipient with a live key. The tool is annotated destructiveHint: true, and its description tells the assistant to confirm with you and run estimate_campaign first.

Input Type Required Constraints
id string yes cmp_…

Returns the progress line with status running (or scheduled).

Example prompt: “The estimate looks right. Start the Weekend offer campaign.”

Pauses a running campaign. Messages already handed to a phone still go out; nothing new is claimed until it resumes.

Input Type Required Constraints
id string yes cmp_…

Returns the progress line with status paused.

Example prompt: “Pause the Weekend offer campaign, there’s a typo.”

Resumes a paused campaign. The throttle restarts from now, so there is no burst.

Input Type Required Constraints
id string yes cmp_…

Returns the progress line with status running.

Example prompt: “Resume the campaign.”

Destructive

Cancels a scheduled, running or paused campaign for good. Pending recipients are skipped and messages no phone has taken yet are blocked. It cannot be undone. The tool is annotated destructiveHint: true.

Input Type Required Constraints
id string yes cmp_…

Returns the progress line with status canceled.

Example prompt: “Cancel the Weekend offer campaign completely.”