Queue outbound SMS text message(s) from your Agent
Queue SMS Tasks for one target and message or up to 10,000 targets. The endpoint accepts Task goals, retry policies, organization defaults, external correlation IDs, metadata, and Contact List enrollment. Submissions over 1,000 targets require Idempotency-Key and return 202.
OpenAPI
````yaml post /api/v2/agent/outboundSms
openapi: 3.0.0
info:
version: 2.0.0
title: GetVoiceBot API
description: GetVoiceBot API Documentation
servers:
- url: https://api.getvoicebot.com
description: GetVoiceBot Production
variables:
baseUrl:
default: api.getvoicebot.com
description: Production API Root
security: []
tags:
- name: Agents
- name: Inbound Email
description: Control which senders may create inbound email work for an Agent.
- name: Features
description: Inspect capabilities available within an account hierarchy.
- name: Conversation Logs
description: Query conversation activity and calculate account-level metrics.
- name: Computer Agents
description: Set up, configure, inspect, and manage GetVoiceBot Computer Agents.
- name: Computer Agent Sessions
description: View and reset Computer Agent sessions.
- name: Accounts
- name: Agent Templates
description: Create, manage, and apply reusable Agent configurations.
paths:
/api/v2/agent/outboundSms:
post:
tags:
- Agents
summary: Queue outbound SMS text message(s) from your Agent
description: >-
Queue SMS Tasks for one target and message or up to 10,000 targets. The
endpoint accepts Task goals, retry policies, organization defaults,
external correlation IDs, metadata, and Contact List enrollment.
Submissions over 1,000 targets require Idempotency-Key and return 202.
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: object
properties:
type:
type: string
example: string
maxLength:
type: number
example: 200
description: >-
Required for submissions over 1,000 targets. Repeating the same key
and payload safely resumes or returns that submission.
requestBody:
required: true
content:
application/json:
schema:
type: object
oneOf:
- type: object
required:
- target
- content
properties:
target:
type: string
description: Phone in E.164 or GetVoiceBot username
example: '+1234567890'
content:
type: string
description: Message body
example: Hello from Acme. Your appointment is tomorrow at 10am.
context:
type: string
description: Optional context for the agent handling the conversation
taskContext:
type: string
description: Task-specific context for this message
accountId:
type: integer
description: Optional agent account id override for the message
agentId:
type: integer
description: Optional campaign id override
scheduledFor:
type: integer
description: Unix seconds to schedule delivery
goal:
type: object
nullable: true
description: >-
Task-specific goal with completionCriteria. Omit or pass
null to use the organization default.
retryPolicy:
type: object
nullable: true
description: >-
Task-specific cadence using delaysSeconds or
mixed-channel steps, retryOn, and optional
responseTimeoutSeconds. Omit or pass null to use the
organization default.
meta:
type: object
description: Optional metadata
externalTaskId:
type: string
description: >-
Reusable customer correlation/grouping ID; not an
idempotency key
contactListName:
type: string
description: Optional Contact List to enroll the contact into
- type: object
required:
- targets
properties:
targets:
description: Array of destinations or objects with per-item options
oneOf:
- type: array
items:
type: string
example: '+1234567890'
- type: array
items:
type: object
required:
- target
properties:
target:
type: string
example: '+1234567890'
content:
type: string
description: Per-item message body
context:
type: string
taskContext:
type: string
accountId:
type: integer
agentId:
type: integer
scheduledFor:
type: integer
goal:
type: object
description: Goal for this Task
retryPolicy:
type: object
description: >-
Per-target retry override; null uses the
organization default
meta:
type: object
contactListName:
type: string
externalTaskId:
type: string
description: Identifier applied to this task
content:
type: string
description: >-
Message applied to all when targets is an array of
strings
context:
type: string
description: Context applied to all items when not provided per item
taskContext:
type: string
description: >-
Task-specific context applied to all items when not
provided per item
accountId:
type: integer
description: >-
Agent account id applied to all items when not provided
per item
agentId:
type: integer
description: Agent id applied to all items
scheduledFor:
type: integer
description: Schedule applied to all items
goal:
type: object
description: >-
Goal applied to each Task unless that item provides its
own
retryPolicy:
type: object
description: >-
Task-specific retry override applied to all items;
omitted or null values use the organization default
scheduleSpacingSec:
type: integer
description: >-
If provided, stagger scheduledFor by this many seconds
per index
example: 15
meta:
type: object
description: Metadata applied to all items
externalTaskId:
type: string
description: >-
Reusable correlation/grouping ID applied to all created
Tasks
contactListName:
type: string
description: Contact List to enroll every contact into
examples:
single:
summary: Single target
value:
target: '+15551234567'
content: Hi, quick reminder for tomorrow at 10am.
context: Reminder campaign
batchStrings:
summary: Multiple string targets with shared content
value:
targets:
- '+15551230001'
- '+15551230002'
- '+15551230003'
content: Thanks for signing up. Reply YES to confirm.
context: Onboarding nudge
scheduleSpacingSec: 10
batchObjects:
summary: Multiple object targets with per-item overrides
value:
targets:
- target: '+15551230001'
content: VIP reminder 9am
context: VIP
scheduledFor: 1730000000
- target: '+15551230002'
content: Standard reminder 10am
agentId: 1234
responses:
'200':
description: Queued successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Outbound SMS initiated.
inserted:
type: integer
example: 3
batchId:
type: string
example: f52b1e01-5cbc-483c-9939-3bf7d37e1426
tasks:
type: array
items:
type: object
'202':
description: Large SMS Task submission accepted for asynchronous creation
'400':
description: Bad Request
'401':
description: Unauthorized
'409':
description: Idempotency conflict or overlapping active retryable Task
'500':
description: Server Error
security:
- apiKeyAuth: []
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: query
name: token
description: GetVoiceBot API Token
````