Oneshot Messaging

OneShot — SMS & Voice

Set up auth/wallet via the oneshot skill, then:

import { OneShot } from '@oneshot-agent/sdk';
const agent = await OneShot.create({ cdp: true });

SMS — agent.sms(options)

const res = await agent.sms({
  message: 'Your appointment is confirmed for Tuesday 2pm.', // max 1600 chars
  to_number: '+15551234567',     // string | string[] (max 10 recipients), E.164
  maxCost: 0.20,
  memo: 'appointment confirmation',
});
// res.{ sent, failed, total, details: [{ to, status, message_sid?, error? }] }

SMS inbox

const inbox = await agent.smsInboxList({ limit: 50, from: '+15551234567', since: '2026-06-01T00:00:00Z' });
// inbox.messages: [{ id, from, to, body, media_urls?, thread_id?, received_at }]

const msg = await agent.smsInboxGet('message_id');

smsInboxList/smsInboxGet are free. The SDK signs a read proof (x-agent-proof) so the API can confirm you own the wallet before returning your messages — automatic; use @oneshot-agent/sdk ≥ 0.25.0 / oneshot-python ≥ 0.17.0.

Voice — agent.voice(options)

Places an outbound call where the OneShot agent pursues your objective, then returns the outcome.

const call = await agent.voice({
  objective: 'Schedule a 30-minute demo for next Tuesday or Wednesday afternoon.',
  target_number: '+15551234567',           // string | string[]; array → conference-mode analysis
  caller_persona: 'A friendly scheduling assistant for Acme Corp.', // optional
  context: 'Following up on our email exchange about the demo.',     // optional
  max_duration_minutes: 10,                 // optional, 1–30
  maxCost: 4.00,
  memo: 'demo scheduling call',
});
// call.{ status, duration_seconds?, transcript?, summary?, success_evaluation?, structured_data? }

Options (VoiceCallOptions):

| Field | Notes | |-------|-------| | objective | Required. What the call should accomplish. | | target_number | Required. string \| string[] in E.164. An array triggers conference-mode. | | caller_persona | Optional persona for the caller. | | context | Optional background for the call. | | max_duration_minutes | Optional, 1–30. |

Voice and SMS are async — they poll to completion by default (wait: true); set wait: false to receive a request_id and poll yourself. Both may include a one-time phone registration fee the first time the agent provisions a number (surfaced in the quote / needs_phone_registration).

> Calling/texting an emergency number throws EmergencyNumberError.

Pricing

Inbox reads are free; SMS and voice are paid, and a one-time phone registration fee applies on first use (surfaced in the quote). See current per-tool pricing at https://docs.oneshotagent.com/pricing. Always pass maxCost on voice (duration-based) and on multi-recipient sms.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: oneshot-agent
• Source: oneshot-agent/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.