> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phonovation.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send binary SMS message
> Send single or multiple binary messages to one or more destination address. The API response will not contain the final delivery status, use [Delivery Reports](https://www.phonovation.com/docs/api/channels/sms/sms-messaging/logs-and-status-reports/receive-outbound-sms-message-report) instead.\
In light of improved features, this endpoint has been superseded. Please visit [Send SMS message](#channels/sms/send-sms-messages) for the next version.
**Required scope:** Enable one of: `message:send`, `sms:message:send`, `sms:manage`.
## OpenAPI
````yaml /openapi/phonovation-whatsapp.json post /sms/2/binary/advanced
openapi: 3.1.0
info:
title: Phonovation Messaging APIs
description: >-
OpenAPI specification for Phonovation messaging, customer engagement, and
platform APIs.
contact:
name: Phonovation support
email: support@phonovation.com
version: 3.250.0
x-generatedAt: '2026-10-15T11:28:56.135064395Z'
servers:
- url: https://api.messaging.phonovation.com
description: Phonovation Messaging API production server
security: []
tags:
- name: customer-engagement
description: >
Complete solutions that will help you drive better outcomes for your
customers and business across the entire customer journey.
x-type: category
x-displayName: Customer Engagement
- name: people
description: >
Build rich profiles for each person to create audience segments for more
precise targeting. Manage duplicates and import your data over API.
Events reflect actions that end users take on your website or in your
mobile application.
Events API is a robust way to send those events to Phonovation. Event can
be sent only to an existing person in People module and an event
definition should be created beforehand to describe contents of the event.
Other events tracking options:
* [ JavaScript SDK ](https://github.com/phonovation/people-web-sdk)
* [iOS
SDK](https://github.com/phonovation/mobile-messaging-sdk-ios/wiki/Events)
* [Android
SDK](https://github.com/phonovation/mobile-messaging-sdk-android/wiki/Events)
x-type: product
x-displayName: People
- name: person-profile
description: ''
x-type: section
x-displayName: Person profile
- name: company-profile
description: ''
x-type: section
x-displayName: Company profile
- name: tags
description: ''
x-type: section
x-displayName: Tags
- name: custom-attributes
description: ''
x-type: section
x-displayName: Custom attributes
- name: custom-attributes-lists
description: ''
x-type: section
x-displayName: 'Custom attributes: Lists'
- name: contact-information:-push
description: ''
x-type: section
x-displayName: 'Contact Information: Push'
- name: events
description: ''
x-type: section
x-displayName: Events
- name: segments
description: ''
x-type: section
x-displayName: Segments
- name: moments
description: >
Use Moments to set up and manage automated messaging campaigns with your
customers by building conversation workflows.
x-type: product
x-displayName: Moments
- name: flow
description: >
[Flow](https://www.phonovation.com/docs/moments/manage-flow) is the
Phonovation communication builder that helps you create and manage
messaging campaigns. The Flows API allows you to add or remove people from
communication programmatically for flows with an [active
status](https://www.phonovation.com/docs/moments/manage-flow#launch-create).
Use the Add Participants to flow endpoint to a person or batches of
persons (between 1-1000 persons). The method works asynchronously to queue
and process participants at a rate of 10 requests per second. For
reporting of operation results, use the notifyUrl field to provide a URL
of your callback server that will receive a status report or use the Get a
report on participants added to Flow endpoint.
x-type: module
x-displayName: Flow
- name: conversations
description: >-
Conversations is a solution that allows Enterprises to engage in
conversations with their customers over multiple channels. The solution is
available either as a web-based cloud platform web interface or over HTTP
API for 2-way messaging over SMS, WhatsApp, Viber, and Facebook messenger.
It supports conversation threading, conversation management including
queues and routing, agent assignment, resolution management and
conversation history overview.
x-type: product
x-displayName: Conversations
- name: conversation-management
description: ''
x-type: section
x-displayName: Conversation management
- name: conversation-tags
description: ''
x-type: section
x-displayName: Conversation tags
- name: conversation-messages
description: ''
x-type: section
x-displayName: Conversation messages
- name: conversation-events
description: ''
x-type: section
x-displayName: Conversation events
- name: conversation-notes
description: ''
x-type: section
x-displayName: Conversation notes
- name: conversation-agents
description: ''
x-type: section
x-displayName: Conversation agents
- name: conversation-queues
description: ''
x-type: section
x-displayName: Conversation queues
- name: conversation-routing
description: ''
x-type: section
x-displayName: Conversation routing
- name: bots
description: ''
x-type: section
x-displayName: Bots
- name: metadata
description: ''
x-type: section
x-displayName: Metadata
- name: templates
description: ''
x-type: section
x-displayName: Templates
- name: conversation-forms
description: ''
x-type: section
x-displayName: Conversation forms
- name: account-configuration
description: ''
x-type: section
x-displayName: Account Configuration
- name: agent-configuration-calls
description: ''
x-type: section
x-displayName: Agent Configuration (Calls)
- name: outbound-call-conversation-calls
description: ''
x-type: section
x-displayName: Outbound Call Conversation (Calls)
- name: waiting-strategies-calls
description: ''
x-type: section
x-displayName: Waiting Strategies (Calls)
- name: recording-configuration-calls
description: ''
x-type: section
x-displayName: Recording Configuration (Calls)
- name: recording-metadata-calls
description: ''
x-type: section
x-displayName: Recording metadata (Calls)
- name: recording-calls
description: ''
x-type: section
x-displayName: Recording (Calls)
- name: wrap-up-configuration-calls
description: ''
x-type: section
x-displayName: Wrap Up Configuration (Calls)
- name: wrap-up-time-calls
description: ''
x-type: section
x-displayName: Wrap Up Time (Calls)
- name: transfers-calls
description: ''
x-type: section
x-displayName: Transfers (Calls)
- name: transfer-to-external-number-configuration-calls
description: ''
x-type: section
x-displayName: Transfer to External Number Configuration (Calls)
- name: transfer-strategy-calls
description: ''
x-type: section
x-displayName: Transfer Strategy (Calls)
- name: call-hold-calls
description: ''
x-type: section
x-displayName: Call Hold (Calls)
- name: hold-configuration-calls
description: ''
x-type: section
x-displayName: Hold Configuration (Calls)
- name: call-timeout-calls
description: ''
x-type: section
x-displayName: Call Timeout (Calls)
- name: working-hours
description: ''
x-type: section
x-displayName: Working Hours
- name: tts-options-calls
description: ''
x-type: section
x-displayName: TTS options (Calls)
- name: away-audio-messages
description: ''
x-type: section
x-displayName: Away Audio Messages
- name: web-forms
description: ''
x-type: section
x-displayName: Web Forms
- name: answers
description: >
Answers is the Phonovation fully-encompassed chatbot building platform
that enables you to build, test, and deploy highly customized chatbots of
different types. Multiple channels are supported on Answers like WhatsApp,
Facebook Messenger, Live Chat, Apple Business Chat, Viber, Google Business
Messaging and other. Communication with Bot is achieved through existing
Conversations solution infrastructure which enables integration and
switching between communicating with bot and a live agent. Processing can
start by receiving MO message or by receiving a trigger event. Users can
manage bots (create, update, delete, start and stop bots) through a web
interface. For more details, visit the [Answers
documentation](https://www.phonovation.com/docs/answers).
Answers API is in Early access stage.
x-type: product
x-displayName: Answers
- name: answers-testing-start-test
description: ''
x-type: section
x-displayName: Start Answers test
- name: answers-testing-stop-test
description: ''
x-type: section
x-displayName: Stop Answers test
- name: answers-testing-send-message
description: ''
x-type: section
x-displayName: Send inbound message to test
- name: common-assets
description: >
Reuse assets created on Phonovation SaaS products in order to recreate
configuration more easily on a single or across multiple accounts. Export
or share Moments flows, Answers chatbots or other SaaS assets from your
account and import it on another one.
This feature is in Early access stage.
x-type: product
x-displayName: Common Assets
- name: saas-resource-export
description: ''
x-type: section
x-displayName: Export resource
- name: saas-resource-import
description: ''
x-type: section
x-displayName: Import resource
- name: saas-resource-share
description: ''
x-type: section
x-displayName: Share resource
- name: saas-status-request
description: ''
x-type: section
x-displayName: Get SaaS request status
- name: knowledge-base
description: >-
Knowledge Base is a centralized content management system for creating,
organizing, and retrieving articles, attachments, and structured content.
Content is organized into categories, folders, and a hierarchical content
tree. Articles support draft and published workflow statuses, tagging,
commenting, and file attachments.
x-type: product
x-displayName: Knowledge Base
- name: knowledge-base-search
description: ''
x-type: section
x-displayName: Search
- name: knowledge-base-articles
description: ''
x-type: section
x-displayName: Articles
- name: knowledge-base-categories
description: ''
x-type: section
x-displayName: Categories
- name: knowledge-base-folders
description: ''
x-type: section
x-displayName: Folders
- name: knowledge-base-content-tree
description: ''
x-type: section
x-displayName: Content Tree
- name: knowledge-base-tags
description: ''
x-type: section
x-displayName: Tags
- name: knowledge-base-attachments
description: ''
x-type: section
x-displayName: Attachments
- name: ai-hub
description: >
AI-powered tools and services to help you create smarter and more
personalized customer experiences.
x-type: category
x-displayName: AI Hub
- name: ai-assistants
description: >
Phonovation AI assistant is a retrieval-augmented generation (RAG)
solution that performs tasks based on documents and
instructions you specify. This means the AI draws answers directly from
your documents, resulting in more accurate
and relevant responses. For more information on use cases and how to build
AI assistants, visit our
[AI Assistant](https://www.phonovation.com/docs/ai-hub/ai-assistant)
product documentation.
With AI Assistants API, you can:
* Query your existing AI assistants created via [Phonovation
Portal](https://www.phonovation.com/docs/ai-hub/ai-assistant/create-ai-assistant)
* Retrieve context the AI assistant uses to answer your queries
x-type: product
x-displayName: AI Assistants
- name: channels
description: >
Create a perfect customer experience by using the channels your customer
already use and love.
x-type: category
x-displayName: Channels
- name: sms
description: >
SMS (Short Message Service) is the most extensive messaging service
available in terms of reach and coverage. A SMS can be sent to and from
any mobile device in the world and does not necessarily require a data
connection.
Phonovation SMS API allows you to send and receive text messages (SMS),
fetch or receive delivery reports on your endpoint in real time, and see
message logs. You can send messages in different languages, schedule your
messages, define delivery time window, and much more.
To utilize SMS in combination with other channels, check out [Messages
API](https://www.phonovation.com/docs/api/platform/messages-api).
x-type: product
x-displayName: SMS
- name: outbound-sms
description: >
When you send an SMS to a phone number belonging to an end user's device
you are sending an Outbound SMS. Historically, this was and still is
referred to as a Mobile Terminated (MT) SMS, though nowadays an SMS is not
always sent to a mobile device. In an Outbound SMS you can set the From or
Sender field with whatever you have registered or purchased with
Phonovation, either a Long Number, Short Code, or text based Sender.
x-type: module
x-displayName: Outbound SMS
- name: send-message
description: ''
x-type: section
x-displayName: Send a message
- name: manage-scheduled-sms-messages
description: ''
x-type: section
x-displayName: Manage Scheduled SMS Messages
- name: confirm-conversion
description: ''
x-type: section
x-displayName: Confirm conversion
- name: inbound-sms
description: >
When an end user sends an SMS from their device to a Phone Number or Short
Code they have sent an Inbound SMS. The Inbound SMS is routed to the
Phonovation Platform and Phonovation in turn routes the SMS to its
Customer who has purchased that Phone Number or Short Code. Inbound SMS,
for historical reasons, are referred to as Mobile Originated (MO) SMS.
x-type: module
x-displayName: Inbound SMS
- name: logs-and-status-reports
description: >
Status Reports tell you what happened to the SMS you sent, whether it was
successfully delivered or failed to be delivered.
They also provide timestamps, network information if available, and on SMS
delivery failure, a status code indicating the reason.
Status Reports can be pushed in real-time to a Customer's webhook or can
be retrieved by an API call.
Logs provide similar information to Status Reports but are available to
query for 48hrs.
x-type: module
x-displayName: Logs and Status Reports
- name: whatsapp
description: >
With 2 billion users, WhatsApp is the most used application worldwide. It
enables you to reach more customers, sharing important and timely
notifications, as well as provide real-time customer support. Phonovation
is an official WhatsApp Business solution provider. Send and manage
WhatsApp messages over Phonovation's WhatsApp API.
To utilize WhatsApp in combination with other channels, check out
[Messages
API](https://www.phonovation.com/docs/api/platform/messages-api).
[Learn more about WhatsApp channel and use
cases](https://www.phonovation.com/docs/whatsapp).
x-type: product
x-displayName: WhatsApp
- name: whatsapp-outbound-messages
description: >
When you send a WhatsApp message to a phone number belonging to an end
user's device you are sending an outbound WhatsApp message.
There are several types of WhatsApp messages:
- Template message – use a pre-defined template to send text, images, videos, share location, documents, attach buttons, and configure SMS failover.
- Free-form text or media – use it only when contacted by the end user within a certain timeframe to send text, images, audio, video, stickers, share location, or contacts.
- Interactive messages – send a message that your end user can interact with, such as interactive buttons, lists, or product messages.
x-type: module
x-displayName: Outbound messages
- name: whatsapp-template-message
description: ''
x-type: section
x-displayName: Template Message
- name: whatsapp-text-and-media-messages
description: ''
x-type: section
x-displayName: Text and media messages
- name: send-whatsapp-interactive-messages
description: ''
x-type: section
x-displayName: Interactive messages
- name: whatsapp-events
description: ''
x-type: section
x-displayName: Events
- name: whatsapp-inbound-messages
description: >
When the end user sends a WhatsApp from their device to a phone number,
they have sent an inbound WhatsApp message.
The inbound message is routed to the Phonovation Platform and Phonovation
in turn routes the message to its customer who has registered the WhatsApp
sender.
Typical supporting features you’d use with inbound messages are:
- Marking messages as read to communicate to the end user that you have read their message.
- Downloading media and its metadata sent over by the end user.
x-type: module
x-displayName: Inbound messages
- name: whatsapp-receive-inbound-message
description: ''
x-type: section
x-displayName: Receive inbound message
- name: whatsapp-get-inbound-media
description: ''
x-type: section
x-displayName: Get inbound media
- name: whatsapp-mark-message-as-read
description: ''
x-type: section
x-displayName: Mark message as read
- name: whatsapp-message-status-reports
description: >
Status Reports tell you what happened to the WhatsApp message you sent,
whether it was successfully delivered or failed to be delivered, whether
it’s been seen.
Status Reports can be pushed in real time to a customer's webhook or can
be retrieved by an API call.
Logs provide similar information to Status Reports but are only available
to query for 48hrs.
There are a few reports you can set up for your WhatsApp messaging:
- Delivery Reports - In case of a failure, you’ll receive a timestamp with a delivery failure message and a status code indicating the reason behind it.
- Seen Reports – In case the message has been delivered successfully to the end user, this report will additionally inform you whether the message has been seen.
- Payments - It provides all updates to your payment transaction in real time. It's also possible to fetch current state of the payment transaction in any time.
x-type: module
x-displayName: Message Status Reports
- name: whatsapp-status-reports
description: ''
x-type: section
x-displayName: Status Reports
- name: whatsapp-payments
description: ''
x-type: section
x-displayName: Payments
- name: whatsapp-marketing-update
description: ''
x-type: section
x-displayName: Marketing Update
- name: whatsapp-service-management
description: >
As opposed to free-form messages, template messages can be sent and
delivered at any time.
Here, you can manage your templates, from template registration,
retrieving template statuses, to deleting existing templates.
With each WhatsApp message, you can send various types of media. Here, you
can manage your media and configure additional feature enhancing their
functionality.
Moreover you can fetch quality and business info of your senders.
x-type: module
x-displayName: Service Management
- name: whatsapp-template-management
description: ''
x-type: section
x-displayName: Template Management
- name: whatsapp-flow-management
description: ''
x-type: section
x-displayName: Flow Management
- name: whatsapp-media-management
description: ''
x-type: section
x-displayName: Media Management
- name: whatsapp-sender-management
description: ''
x-type: section
x-displayName: Sender Management
- name: whatsapp-bulk-sender-registration
description: ''
x-type: section
x-displayName: Bulk Sender Registration
- name: whatsapp-identity-management
description: >
Set up identity change, an add-on available for senders hosted by
Phonovation. This is supported for interactive buttons, interactive lists,
or an interactive product message.
Identity change allows you to increase your security by preventing
messages from being sent to unverified end users.
Once enabled for a sender, you would receive notifications when an end
user's WhatsApp account (MSISDN) has potentially been transferred to a
different user.
When a potential identity change has been detected, the outbound traffic
towards that end user is blocked until you verify the user outside the
channel and acknowledge the change.
Contact your Account Executive for more information.
x-type: module
x-displayName: Identity Management
- name: whatsapp-ad-conversions
description: >
The Conversions API for Business Messaging enables advertisers to
consolidate web, app, physical store, and business messaging events into a
single endpoint for Meta. With Phonovation, you can submit Purchase or
LeadSubmitted conversion events for WhatsApp.
x-type: module
x-displayName: Ad Conversions
- name: platform
description: |
Modular tools to scale and automate your business.
x-type: category
x-displayName: Platform
- name: subscriptions-api
description: >
Subscriptions are a way to manage notifications sent to your webhooks by
Phonovation.
It is a useful feature if you want to narrow down the list of events to be
notified about or specify different webhooks for different use cases.
It will also allow you to set up authentication settings for your
endpoint.
If you want to use mutual TLS for the webhook that receives notification
events from Phonovation, you can upload and manage a TLS certificate that
Phonovation will use when connecting to your server. The certificate
allows your server to verify that the request is really coming from
Phonovation. For details, see [Create and Manage
Certificates](https://www.phonovation.com/docs/cpaas-x/subscriptions-management/create-manage-subscriptions#create-and-manage-certificates).
x-type: product
x-displayName: Subscriptions Management
- name: subscription
description: ''
x-type: section
x-displayName: Subscription
- name: profile
description: ''
x-type: section
x-displayName: Profile
- name: security
description: ''
x-type: section
x-displayName: Security
- name: certificate
description: ''
x-type: section
x-displayName: Certificate
paths:
/sms/2/binary/advanced:
post:
tags:
- channels
- sms
- outbound-sms
- send-message
summary: Send binary SMS message
description: >-
Send single or multiple binary messages to one or more destination
address. The API response will not contain the final delivery status,
use [Delivery
Reports](https://www.phonovation.com/docs/api/channels/sms/sms-messaging/logs-and-status-reports/receive-outbound-sms-message-report)
instead.\
In light of improved features, this endpoint has been superseded. Please
visit [Send SMS message](#channels/sms/send-sms-messages) for the next
version.
**Required scope:** Enable one of: `message:send`, `sms:message:send`,
`sms:manage`.
operationId: send-binary-sms-message
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/7b23cc7ec456214e90b61e3d5abd3aaf7422ea4b20f1cdd2d4e9c44fbceaf035.SMSAdvancedBinaryRequest
examples:
Send fully-featured binary message:
summary: Send fully-featured binary message
value:
bulkId: BULK-ID-123-xyz
messages:
- binary:
dataCoding: 0
esmClass: 0
hex: 54 65 73 74 20 6d 65 73 73 61 67 65 2e
callbackData: DLR callback data
destinations:
- messageId: MESSAGE-ID-123-xyz
to: '353861234579'
- to: '353861234582'
from: InfoSMS
intermediateReport: true
notifyContentType: application/json
notifyUrl: https://www.example.com/sms/advanced
validityPeriod: 720
campaignReferenceId: summersale
- binary:
dataCoding: 0
esmClass: 0
hex: 41 20 6C 6F 6E 67 20 74 …20 45 6D 70 69 72 65 2E
deliveryTimeWindow:
days:
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
- SUNDAY
from:
hour: 6
minute: 0
to:
hour: 15
minute: 30
destinations:
- to: '353861234578'
from: '353861234578'
sendAt: 2021-08-25T16:00:00.000+0000
Unicode flash binary SMS:
summary: Unicode flash binary SMS
description: Send Unicode flash SMS m… over binary API method
value:
messages:
- binary:
dataCoding: 8
esmClass: 0
hex: >-
0048 0065 006c 006c 006f 0020 0077 006f 0072 006c 0064
002c 0020 039a 03b1 03bb 03b7 03bc 03ad 03c1 03b1 0020
03ba 03cc 03c3 03bc 03b5 002c 0020 30b3 30f3 30cb 30c1
30cf
destinations:
- to: '353861234579'
flash: true
from: InfoSMS
application/xml:
schema:
$ref: >-
#/components/schemas/7b23cc7ec456214e90b61e3d5abd3aaf7422ea4b20f1cdd2d4e9c44fbceaf035.SMSAdvancedBinaryRequest
examples:
Send fully-featured binary message:
summary: Send fully-featured binary message
value: >
BULK-ID-123-xyz
0
0
54 65 73 74 20 6d 65 73 73 61 67 65 2e
DLR callback data
InfoSMS
true
application/json
https://www.example.com/sms/advanced
720
summersale
MESSAGE-ID-123-xyz
353861234579
353861234582
0
0
41 20 6C 6F 6E 67 20 74 …20 45 6D 70 69 72 65 2E
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY
6
0
15
30
353861234578
2021-08-25T16:00:00.000+0000
353861234578
Unicode flash binary SMS:
summary: Unicode flash binary SMS
description: Send Unicode flash SMS m… over binary API method
value: >
8
0
0048 0065 006c 006c 006f 0020 0077 006f 0072 006c 0064 002c 0020 039a 03b1 03bb 03b7 03bc 03ad 03c1 03b1 0020 03ba 03cc 03c3 03bc 03b5 002c 0020 30b3 30f3 30cb 30c1 30cf
true
InfoSMS
353861234579
required: true
responses:
'200':
description: successful response
content:
application/json:
schema:
$ref: >-
#/components/schemas/33e5f9b198702dad16ca1f81c1bb567a11b08d145013a25f78031b56a52d656b.SMSResponse
examples:
Response for request with one destination:
summary: Response for request with one destination
value:
bulkId: '2034072219640523072'
messages:
- messageId: 2250be2d4219-3af1-78856-aabe-1362af1edfd2
status:
description: Message sent to next instance
groupId: 1
groupName: PENDING
id: 26
name: PENDING_ACCEPTED
to: '353861234579'
Response for request with multiple destinations:
summary: Response for request with multiple destinations
value:
bulkId: '2034072219640523073'
messages:
- messageId: '2033247207850523791'
status:
description: Message sent to next instance
groupId: 1
groupName: PENDING
id: 26
name: PENDING_ACCEPTED
to: '353861234579'
- messageId: '2033247207850523792'
status:
description: Message sent to next instance
groupId: 1
groupName: PENDING
id: 26
name: PENDING_ACCEPTED
to: '353861234582'
application/xml:
schema:
$ref: >-
#/components/schemas/33e5f9b198702dad16ca1f81c1bb567a11b08d145013a25f78031b56a52d656b.SMSResponse
examples:
Response for request with one destination:
summary: Response for request with one destination
value: |
2034072219640523072
2250be2d4219-3af1-78856-aabe-1362af1edfd2
Message sent to next instance
1
PENDING
26
PENDING_ACCEPTED
353861234579
Response for request with multiple destinations:
summary: Response for request with multiple destinations
value: |
2034072219640523073
2033247207850523791
Message sent to next instance
1
PENDING
26
PENDING_ACCEPTED
353861234579
2033247207850523792
Message sent to next instance
1
PENDING
26
PENDING_ACCEPTED
353861234582
'400':
description: Error responses
content:
application/json:
schema:
$ref: >-
#/components/schemas/578c889dd8f68587bd351066c5c6572a98ea0c15c65b5cacb8779be90fbfbb70.ApiException
examples:
Bad request:
summary: Bad request
value:
requestError:
serviceException:
messageId: BAD_REQUEST
text: Bad request
application/xml:
schema:
$ref: >-
#/components/schemas/578c889dd8f68587bd351066c5c6572a98ea0c15c65b5cacb8779be90fbfbb70.ApiException
examples:
Bad request:
summary: Bad request
value: |
BAD_REQUEST
Bad request
'401':
$ref: '#/components/responses/ApiException401'
'403':
$ref: '#/components/responses/ApiException403'
'500':
$ref: '#/components/responses/ApiException500'
security:
- APIKeyHeader: []
externalDocs:
description: Learn more about SMS channel and use cases
url: https://www.phonovation.com/docs/sms
components:
schemas:
7b23cc7ec456214e90b61e3d5abd3aaf7422ea4b20f1cdd2d4e9c44fbceaf035.SMSAdvancedBinaryRequest:
type: object
properties:
bulkId:
type: string
description: >-
Unique ID assigned to the request if messaging multiple recipients
or sending multiple messages via a single API request. If not
provided, it will be auto-generated and returned in the API
response. Typically, used to fetch [delivery
reports](#channels/sms/get-outbound-sms-message-delivery-reports)
and [message logs](#channels/sms/get-outbound-sms-message-logs).
Anything above 100 characters passed in the request will be clipped
during processing and returned in response, reports and logs.
messages:
type: array
description: >-
An array of message objects of a single message or multiple messages
sent under one bulk ID.
items:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.SMSBinaryMessage
minItems: 1
sendingSpeedLimit:
$ref: >-
#/components/schemas/87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.SendingSpeedLimit
required:
- messages
title: SMSAdvancedBinaryRequest
33e5f9b198702dad16ca1f81c1bb567a11b08d145013a25f78031b56a52d656b.SMSResponse:
type: object
properties:
bulkId:
type: string
description: >-
Unique ID assigned to the request if messaging multiple recipients
or sending multiple messages via a single API request. Typically,
used to fetch [delivery
reports](#channels/sms/get-outbound-sms-message-delivery-reports)
and [message logs](#channels/sms/get-outbound-sms-message-logs).
readOnly: true
messages:
type: array
description: >-
An array of message objects of a single message or multiple messages
sent under one bulk ID.
items:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.SMSResponseDetails
readOnly: true
title: SMSResponse
578c889dd8f68587bd351066c5c6572a98ea0c15c65b5cacb8779be90fbfbb70.ApiException:
type: object
properties:
requestError:
$ref: '#/components/schemas/ApiRequestError'
title: ApiException
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.SMSBinaryMessage:
type: object
description: >-
An array of message objects of a single message or multiple messages
sent under one bulk ID.
properties:
binary:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.BinaryContent
callbackData:
type: string
description: >-
Additional data that can be used for identifying, managing, or
monitoring a message. Data included here will also be automatically
included in the message [Delivery
Report](#channels/sms/get-outbound-sms-message-delivery-reports).
The maximum value is 4000 characters.
maxLength: 4000
minLength: 0
writeOnly: true
deliveryTimeWindow:
$ref: >-
#/components/schemas/87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.DeliveryTimeWindow
destinations:
type: array
description: >-
An array of destination objects for where messages are being sent. A
valid destination is required.
items:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.Destination
minItems: 1
writeOnly: true
flash:
type: boolean
description: >-
Allows for sending a [flash
SMS](https://www.phonovation.com/docs/sms/message-types#flash-sms)
to automatically appear on recipient devices without interaction.
Set to `true` to enable flash SMS, or leave the default value,
`false` to send a standard SMS.
writeOnly: true
from:
type: string
description: >-
The sender ID which can be alphanumeric or numeric (e.g.,
`CompanyName`). Make sure you don't exceed [character
limit](https://www.phonovation.com/docs/sms/get-started#sender-names).
writeOnly: true
intermediateReport:
type: boolean
description: >-
The [real-time intermediate delivery
report](https://www.phonovation.com/docs/api#channels/sms/receive-outbound-sms-message-report)
containing GSM error codes, messages status, pricing, network and
country codes, etc., which will be sent on your callback server.
Defaults to `false`.
writeOnly: true
notifyContentType:
type: string
description: >-
Preferred delivery report content type, `application/json` or
`application/xml`.
writeOnly: true
notifyUrl:
type: string
description: >-
The URL on your call back server on which the Delivery report will
be sent.
externalDocs:
description: Delivery report format
url: '#channels/sms/receive-outbound-sms-message-report'
writeOnly: true
regional:
$ref: >-
#/components/schemas/87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.RegionalOptions
sendAt:
type: string
format: date-time
description: >-
Date and time when the message is to be sent. Used for [scheduled
SMS](https://www.phonovation.com/docs/api#channels/sms/get-scheduled-sms-messages).
Has the following format: `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, and can only
be scheduled for no later than 180 days in advance.
writeOnly: true
validityPeriod:
type: integer
format: int64
description: >-
The message validity period in minutes. When the period expires, it
will not be allowed for the message to be sent. Validity period
longer than 48h is not supported (in this case, it will be
automatically set to 48h).
writeOnly: true
entityId:
type: string
description: >-
Required for entity use in a send request for outbound traffic.
Returned in notification events. For more details, see our
[documentation](https://www.phonovation.com/docs/cpaas-x/application-and-entity-management).
maxLength: 66
minLength: 0
writeOnly: true
applicationId:
type: string
description: >-
Required for application use in a send request for outbound traffic.
Returned in notification events. For more details, see our
[documentation](https://www.phonovation.com/docs/cpaas-x/application-and-entity-management).
maxLength: 66
minLength: 0
writeOnly: true
campaignReferenceId:
type: string
description: >-
ID that allows you to track, analyze, and show an aggregated
overview and the performance of individual campaigns per sending
channel.
maxLength: 255
minLength: 0
required:
- destinations
title: SMSBinaryMessage
87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.SendingSpeedLimit:
type: object
description: >-
Limits the send speed when sending messages in bulk to deliver messages
over a longer period of time. You may wish to use this to allow your
systems or agents to handle large amounts of incoming traffic, e.g., if
you are expecting recipients to follow through with a call-to-action
option from a message you sent. Not setting a send speed limit can
overwhelm your resources with incoming traffic.
properties:
amount:
type: integer
format: int32
description: >-
The number of messages to be sent per timeUnit. By default, the
system sends messages as fast as the infrastructure allows. Use this
parameter to adapt sending capacity to your needs. The system is
only able to work against its maximum capacity for ambitious message
batches.
writeOnly: true
timeUnit:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.SpeedLimitTimeUnit
required:
- amount
title: SendingSpeedLimit
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.SMSResponseDetails:
type: object
description: >-
An array of message objects of a single message or multiple messages
sent under one bulk ID.
properties:
messageId:
type: string
description: >-
Unique message ID. If not passed, it will be automatically generated
and returned in a response.
readOnly: true
status:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.Status
to:
type: string
description: The destination address of the message.
readOnly: true
smsCount:
type: integer
format: int32
description: >-
This is the total count of SMS submitted in the request. SMS
messages have a character limit and messages longer than that limit
will be split into multiple SMS and reflected in the total count of
SMS submitted.
readOnly: true
readOnly: true
title: SMSResponseDetails
ApiRequestError:
type: object
properties:
serviceException:
$ref: '#/components/schemas/ApiRequestErrorDetails'
title: ApiRequestError
ApiException:
type: object
properties:
requestError:
$ref: '#/components/schemas/ApiRequestError'
title: ApiException
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.BinaryContent:
type: object
properties:
dataCoding:
type: integer
format: int32
description: >-
Binary content data coding. The default value is (`0`) for GSM7.
Example: (`8`) for Unicode data.
writeOnly: true
esmClass:
type: integer
format: int32
description: >-
“Esm_class” parameter. Indicate special message attributes
associated with the SMS. Default value is (`0`).
writeOnly: true
hex:
type: string
description: >-
Hexadecimal string. This is the representation of your binary data.
Two hex digits represent one byte. They should be separated by the
space character (Example: `0f c2 4a bf 34 13 ba`).
minLength: 1
writeOnly: true
required:
- hex
title: BinaryContent
87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.DeliveryTimeWindow:
type: object
description: >-
Sets specific SMS delivery window outside of which messages won't be
delivered. Often, used when there are restrictions on when messages can
be sent.
properties:
days:
type: array
description: >-
Days of the week which are included in the delivery time window. At
least one day must be provided. Separate multiple days with a comma.
items:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.DeliveryDay
minItems: 1
writeOnly: true
from:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.DeliveryTimeFrom
to:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.DeliveryTimeTo
required:
- days
title: DeliveryTimeWindow
writeOnly: true
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.Destination:
type: object
description: >-
An array of destination objects for where messages are being sent. A
valid destination is required.
properties:
messageId:
type: string
description: >-
The ID that uniquely identifies the message sent. Anything above 200
characters passed in the request will be clipped during processing
and returned in response, reports and logs.
writeOnly: true
to:
type: string
description: >-
Message destination address. Addresses must be in international
format (Example: `353861234579`).
maxLength: 64
minLength: 0
writeOnly: true
required:
- to
title: Destination
writeOnly: true
87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.RegionalOptions:
type: object
description: >-
Region-specific parameters, often imposed by local laws. Use this, if
country or region that you are sending an SMS to requires additional
information.
properties:
indiaDlt:
$ref: >-
#/components/schemas/87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.IndiaDltOptions
turkeyIys:
$ref: >-
#/components/schemas/87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.TurkeyIysOptions
southKorea:
$ref: >-
#/components/schemas/87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.SouthKoreaOptions
title: RegionalOptions
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.SpeedLimitTimeUnit:
type: string
default: MINUTE
description: >-
The time unit to define when setting a messaging speed limit. Defaults
to `MINUTE`.
enum:
- MINUTE
- HOUR
- DAY
title: SpeedLimitTimeUnit
writeOnly: true
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.Status:
type: object
description: >-
Indicates the
[status](https://www.phonovation.com/docs/essentials/response-status-and-error-codes#api-status-codes)
of the message and how to recover from an error should there be any.
properties:
groupId:
type: integer
format: int32
description: Status group ID.
groupName:
type: string
description: >-
Status group name that describes which category the status code
belongs to, e.g. PENDING, UNDELIVERABLE, DELIVERED, EXPIRED,
REJECTED.
id:
type: integer
format: int32
description: Status ID.
name:
type: string
description: >-
[Status
name](https://www.phonovation.com/docs/essentials/response-status-and-error-codes).
description:
type: string
description: Human-readable description of the status.
action:
type: string
description: Action that should be taken to recover from the error.
title: Status
ApiRequestErrorDetails:
type: object
properties:
messageId:
type: string
description: Identifier of the error.
text:
type: string
description: Detailed error description.
validationErrors:
type: object
additionalProperties:
type: array
items:
type: string
description: Validation errors.
description: Validation errors.
title: ApiRequestErrorDetails
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.DeliveryDay:
type: string
description: >-
Days of the week which are included in the delivery time window. At
least one day must be provided. Separate multiple days with a comma.
enum:
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
- SUNDAY
title: DeliveryDay
writeOnly: true
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.DeliveryTimeFrom:
type: object
description: >-
The exact time of day to start sending messages. Time is expressed in
the UTC time zone. If set, use it together with the `to` property with
minimum 1 hour difference.
properties:
hour:
type: integer
format: int32
description: >-
Hour when the time window opens when used in the `from` property or
closes when used in the `to` property.
maximum: 23
minimum: 0
writeOnly: true
minute:
type: integer
format: int32
description: >-
Minute when the time window opens when used in the `from` property
or closes when used in the `to` property.
maximum: 59
minimum: 0
writeOnly: true
required:
- hour
- minute
title: DeliveryTimeFrom
writeOnly: true
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.DeliveryTimeTo:
type: object
description: >-
The exact time of day to end sending messages. Time is expressed in the
UTC time zone. If set, use it together with the `from` property with
minimum 1 hour difference.
properties:
hour:
type: integer
format: int32
description: >-
Hour when the time window opens when used in the `from` property or
closes when used in the `to` property.
maximum: 23
minimum: 0
writeOnly: true
minute:
type: integer
format: int32
description: >-
Minute when the time window opens when used in the `from` property
or closes when used in the `to` property.
maximum: 59
minimum: 0
writeOnly: true
required:
- hour
- minute
title: DeliveryTimeTo
writeOnly: true
87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.IndiaDltOptions:
type: object
description: >-
Distributed Ledger Technology (DLT) specific parameters required for
sending SMS to phone numbers registered in India.
properties:
contentTemplateId:
type: string
description: >-
Registered DLT content template ID which matches message you are
sending.
principalEntityId:
type: string
description: Your assigned DLT principal entity ID.
minLength: 1
telemarketerId:
type: string
description: Your assigned Telemarketer ID. (required for Aggregators)
required:
- principalEntityId
title: IndiaDltOptions
87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.TurkeyIysOptions:
type: object
description: >-
IYS regulations specific parameters required for sending promotional SMS
to phone numbers registered in Turkey.
properties:
brandCode:
type: integer
format: int32
description: >-
Brand code is an ID of the company based on a company VAT number. If
not provided in request, default value is used from your Phonovation
account.
recipientType:
$ref: >-
#/components/schemas/20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.IysRecipientType
required:
- recipientType
title: TurkeyIysOptions
87cf6d665490382407be009353007f071b1d6d4a375e96d31d3bf0b04b7fb3c7.SouthKoreaOptions:
type: object
description: >-
Use case dependent parameters for sending SMS to phone numbers
registered in South Korea.
properties:
resellerCode:
type: integer
format: int32
description: >-
Reseller identification code: 9-digit registration number in the
business registration certificate for South Korea. Resellers should
submit this when sending.
title:
type: string
description: Set the title or subject of a message. South Korea only.
maxLength: 66
minLength: 0
title: SouthKoreaOptions
20085a4036d67f66ebf204560d55d58a7c131c15d42c8ed9442747c488e08630.IysRecipientType:
type: string
description: Recipient Type must be `TACIR` or `BIREYSEL`.
enum:
- BIREYSEL
- TACIR
title: IysRecipientType
responses:
ApiException401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiException'
example:
requestError:
serviceException:
messageId: UNAUTHORIZED
text: Unauthorized
application/xml:
schema:
$ref: '#/components/schemas/ApiException'
example: |
UNAUTHORIZED
Unauthorized
ApiException403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiException'
example:
requestError:
serviceException:
messageId: FORBIDDEN
text: Forbidden
application/xml:
schema:
$ref: '#/components/schemas/ApiException'
example: |
FORBIDDEN
Forbidden
ApiException500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiException'
example:
requestError:
serviceException:
messageId: GENERAL_ERROR
text: Something went wrong. Please contact support.
application/xml:
schema:
$ref: '#/components/schemas/ApiException'
example: |
GENERAL_ERROR
Something went wrong. Please contact support.
securitySchemes:
APIKeyHeader:
type: apiKey
description: >
This is the most secure authorization type and the one with the most
flexibility.
API keys can be generated by calling the dedicated API method.
Furthermore, API keys can have a limited scope and cover only some API
methods. Lastly, they can
be revoked at any time. This range of possibilities makes API keys well
suited for separating the API access rights across multiple applications
or use cases.
Finally, the loss of an API key is easily manageable.
You can manage your API keys from
[GUI](https://portal.phonovation.com/settings/accounts/api-keys), or
programmatically
with [dedicated API](#platform-&-connectivity/settings).
API key Authorization header example:
```shell
Authorization: App
003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
```
name: Authorization
in: header
x-default: 'App '
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.