CAMARA Short Message Service API
Send SMS messages programmatically with operator-delivered routing. Includes a delivery-notification subscription surface for CloudEvents callbacks on message status (delivered, failed, expired).
OpenAPI Specification
openapi: 3.0.3
info:
title: SMS API
description: |
The API provides the customer with the ability to send SMS to the recepient address(es).
Customer can use this API to send SMS in following scenarios:
1. Application server needs to send text message to a recepient number which is being used on a mobile phone device. There are 3 different categories of text SMS i.e. Service, Promotion & Transaction.
2. Application server needs to send binary message to a recepient number which is being used on (IoT) device.
Pre-requisite for using this API is that SMS Sender application / enterprise (or customer) needs to onboard themselves with the access provider before using this API.
This API has single operation to send SMS.
In order to the receive delivery receipt, separate API to be subscribed by the API consumer for receiving the delivery receipt in a standardized callback API.
# Authorization and authentication
CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
version: 0.1.0-alpha.1
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://www.example.com/support
email: support@example.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: Product documentation at Camara
url: https://github.com/camaraproject/ShortMessageService
servers:
- url: '{apiRoot}/{basePath}'
variables:
apiRoot:
default: http://localhost:9091
description: API root
basePath:
default: sms/v0alpha1
description: Base path for the Short Message Service
tags:
- name: Short Message Service
description: API operation to send SMS
paths:
/short-message:
post:
security:
- openId:
- send-sms:short-message
tags:
- Send SMS
summary: Send SMS
description: |
The customer application server makes a request to the SMS API to send SMS message to the destination address.
operationId: send-sms
parameters:
- $ref: '#/components/parameters/x-correlator'
requestBody:
description: |
Submit a request for sending SMS to the destination address
content:
application/json:
schema:
$ref: '#/components/schemas/MessageRequest'
examples:
MessageRequest:
value:
to: ['+910123456789']
from: '+919876543210'
category: PROMOTION
message: xxxxxxxxxx
required: true
responses:
'200':
$ref: '#/components/responses/Generic200'
'400':
$ref: '#/components/responses/Generic400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/Generic403'
'404':
$ref: '#/components/responses/Generic404'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
components:
securitySchemes:
openId:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
parameters:
x-correlator:
name: x-correlator
in: header
description: Correlation id for the different services
schema:
type: string
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
schemas:
MessageRequest:
type: object
required:
- to
- from
- message
properties:
to:
type: array
description: "The recipients MSISDN"
items:
type: string
from:
type: string
description: "The senders MSISDN"
category:
type: string
enum: ["PROMOTION","SERVICE","TRANSACTION"]
message:
type: string
description: "SMS message"
MessageResponse:
type: object
required:
- msgId
- timestamp
properties:
msgId:
type: string
description: "The SMS messages sent to the recipients are identified by smsnumber are identified."
timestamp:
type: string
format: date-time
description: Timestamp when SMS was delivered. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
ErrorInfo:
type: object
required:
- status
- code
- detail
properties:
status:
type: integer
description: HTTP response status code
code:
type: string
description: Code given to this error
detail:
type: string
description: Detailed error description
responses:
Generic200:
description: OK
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
msgId: 56647d96-b3e6-48d2-b93f-ab0d56bdd965
timestamp: "2024-03-19T12:33:27.070Z"
Generic400:
description: Problem with the client request
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 400
code: INVALID_ARGUMENT
detail: Client specified an invalid argument, request body or query param
Generic401:
description: Authentication problem with the client request
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 401
code: UNAUTHENTICATED
detail: Request not authenticated due to missing, invalid, or expired credentials
Generic403:
description: Client does not have sufficient permission
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
PermissionDenied:
value:
status: 403
code: PERMISSION_DENIED
detail: Client does not have sufficient permissions to perform this action
InvalidTokenContext:
value:
status: 403
code: INVALID_TOKEN_CONTEXT
detail: Phone number cannot be deducted from access token context
Generic404:
description: Resource Not Found
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 404
code: NOT_FOUND
detail: A specified resource is not found
Generic500:
description: Server error
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 500
code: INTERNAL
detail: Server error
Generic503:
description: Service unavailable. Typically the server is down.
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 503
code: UNAVAILABLE
detail: Service unavailable