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.

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.

SMS inbox

Voice — agent.voice(options)

Pricing

Voice — `agent.voice(options)`

oneshot-messaging

OneShot — SMS & Voice

SMS — agent.sms(options)

SMS — `agent.sms(options)`