{ "schemes": ["https"], "swagger": "2.0", "info": { "description": "This API provides programmatic access to sending SMS messages on Android devices. Features include sending SMS, checking message status, device management, webhook configuration, and system health checks.", "title": "SMSGate API", "contact": { "name": "SMSGate Support", "url": "https://docs.sms-gate.app/", "email": "support@sms-gate.app" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "1.45.3" }, "host": "api.sms-gate.app", "basePath": "/", "paths": { "/3rdparty/v1/auth/token": { "post": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Generate new access token with specified scopes and ttl", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User", "Auth" ], "summary": "Generate token", "parameters": [ { "description": "Request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/smsgateway.TokenRequest" } } ], "responses": { "201": { "description": "Token", "schema": { "$ref": "#/definitions/smsgateway.TokenResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "501": { "description": "Not implemented", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/auth/token/refresh": { "post": { "security": [ { "JWTAuth": [] } ], "description": "Refresh access token with specified refresh token", "produces": [ "application/json" ], "tags": [ "User", "Auth" ], "summary": "Refresh token", "responses": { "201": { "description": "Token", "schema": { "$ref": "#/definitions/smsgateway.TokenResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "501": { "description": "Not implemented", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/auth/token/{jti}": { "delete": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Revoke access token with specified jti", "produces": [ "application/json" ], "tags": [ "User", "Auth" ], "summary": "Revoke token", "parameters": [ { "type": "string", "description": "JWT ID", "name": "jti", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "501": { "description": "Not implemented", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/devices": { "get": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Returns list of registered devices", "produces": [ "application/json" ], "tags": [ "User", "Devices" ], "summary": "List devices", "responses": { "200": { "description": "Device list", "schema": { "type": "array", "items": { "$ref": "#/definitions/smsgateway.Device" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/devices/{id}": { "delete": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Removes device", "produces": [ "application/json" ], "tags": [ "User", "Devices" ], "summary": "Remove device", "parameters": [ { "type": "string", "description": "Device ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully removed" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/health": { "get": { "description": "Checks if service is ready to serve traffic (readiness probe)", "produces": [ "application/json" ], "tags": [ "System" ], "summary": "Readiness probe", "responses": { "200": { "description": "Service is ready", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } }, "503": { "description": "Service is not ready", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } } } } }, "/3rdparty/v1/inbox": { "get": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Retrieves incoming messages with filtering and pagination.", "produces": [ "application/json" ], "tags": [ "User", "Inbox" ], "summary": "Get incoming messages", "parameters": [ { "enum": [ "SMS", "DATA_SMS", "MMS", "MMS_DOWNLOADED" ], "type": "string", "description": "Filter incoming messages by type", "name": "type", "in": "query" }, { "maximum": 500, "minimum": 1, "type": "integer", "default": 50, "description": "Maximum number of messages to return", "name": "limit", "in": "query" }, { "minimum": 0, "type": "integer", "default": 0, "description": "Number of messages to skip", "name": "offset", "in": "query" }, { "type": "string", "format": "date-time", "description": "Start of date range (ISO 8601)", "name": "from", "in": "query" }, { "type": "string", "format": "date-time", "description": "End of date range (ISO 8601)", "name": "to", "in": "query" }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "query" } ], "responses": { "200": { "description": "A list of incoming messages", "schema": { "type": "array", "items": { "$ref": "#/definitions/smsgateway.IncomingMessage" } }, "headers": { "X-Total-Count": { "type": "integer", "description": "Total number of items available" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "501": { "description": "Not implemented", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/inbox/refresh": { "post": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Refreshes inbox messages. Webhooks are triggered when triggerWebhooks is true.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User", "Inbox" ], "summary": "Request inbox messages refresh", "parameters": [ { "description": "Refresh inbox request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/smsgateway.InboxRefreshRequest" } } ], "responses": { "202": { "description": "Inbox refresh request accepted" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/logs": { "get": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Retrieve a list of log entries within a specified time range.", "produces": [ "application/json" ], "tags": [ "System", "Logs" ], "summary": "Get logs", "parameters": [ { "type": "string", "format": "date-time", "description": "The start of the time range for the logs to retrieve. Logs created after this timestamp will be included.", "name": "from", "in": "query" }, { "type": "string", "format": "date-time", "description": "The end of the time range for the logs to retrieve. Logs created before this timestamp will be included.", "name": "to", "in": "query" } ], "responses": { "200": { "description": "Log entries", "schema": { "type": "array", "items": { "$ref": "#/definitions/smsgateway.LogEntry" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "501": { "description": "Not implemented", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/messages": { "get": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Retrieves a list of messages with filtering and pagination", "produces": [ "application/json" ], "tags": [ "User", "Messages" ], "summary": "Get messages", "parameters": [ { "type": "string", "format": "date-time", "description": "Start date in RFC3339 format", "name": "from", "in": "query" }, { "type": "string", "format": "date-time", "description": "End date in RFC3339 format", "name": "to", "in": "query" }, { "type": "string", "description": "Filter messages by processing state", "name": "state", "in": "query" }, { "type": "string", "description": "Filter by device ID", "name": "deviceId", "in": "query" }, { "type": "integer", "default": 50, "description": "Pagination limit", "name": "limit", "in": "query" }, { "type": "integer", "default": 0, "description": "Pagination offset", "name": "offset", "in": "query" }, { "type": "boolean", "default": false, "description": "Include textMessage/dataMessage content for each message. Default is false", "name": "includeContent", "in": "query" } ], "responses": { "200": { "description": "A list of messages", "schema": { "type": "array", "items": { "$ref": "#/definitions/smsgateway.MessageState" } }, "headers": { "X-Total-Count": { "type": "integer", "description": "Total number of items available" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } }, "post": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Enqueues a message for sending. If `deviceId` is set, the specified device is used; otherwise a random registered device is chosen.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User", "Messages" ], "summary": "Enqueue message", "parameters": [ { "type": "boolean", "description": "Skip phone validation", "name": "skipPhoneValidation", "in": "query" }, { "minimum": 0, "type": "integer", "default": 0, "description": "Filter devices active within the specified number of hours", "name": "deviceActiveWithin", "in": "query" }, { "description": "Send message request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/smsgateway.Message" } } ], "responses": { "202": { "description": "Message enqueued", "schema": { "$ref": "#/definitions/smsgateway.GetMessageResponse" }, "headers": { "Location": { "type": "string", "description": "Get message state URL" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "409": { "description": "Message with such ID already exists", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "503": { "description": "Queue limits exceeded; ensure device is online", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/messages/{id}": { "get": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Returns message state by ID", "produces": [ "application/json" ], "tags": [ "User", "Messages" ], "summary": "Get message state", "parameters": [ { "type": "string", "description": "Message ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Message state", "schema": { "$ref": "#/definitions/smsgateway.GetMessageResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } }, "delete": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Cancels a pending message by ID. The message must be in Pending state.", "tags": [ "User", "Messages" ], "summary": "Cancel message", "parameters": [ { "type": "string", "description": "Message ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Message state after cancellation", "schema": { "$ref": "#/definitions/smsgateway.GetMessageResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "404": { "description": "Message not found", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/settings": { "get": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Returns settings for a specific user", "produces": [ "application/json" ], "tags": [ "User", "Settings" ], "summary": "Get settings", "responses": { "200": { "description": "Settings", "schema": { "$ref": "#/definitions/smsgateway.DeviceSettings" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } }, "put": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Replaces settings", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User", "Settings" ], "summary": "Replace settings", "parameters": [ { "description": "Settings", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/smsgateway.DeviceSettings" } } ], "responses": { "200": { "description": "Settings updated", "schema": { "type": "object" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } }, "patch": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Partially updates settings for a specific user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User", "Settings" ], "summary": "Partially update settings", "parameters": [ { "description": "Settings", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/smsgateway.DeviceSettings" } } ], "responses": { "200": { "description": "Settings updated", "schema": { "type": "object" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/webhooks": { "get": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Returns list of registered webhooks", "produces": [ "application/json" ], "tags": [ "User", "Webhooks" ], "summary": "List webhooks", "responses": { "200": { "description": "Webhook list", "schema": { "type": "array", "items": { "$ref": "#/definitions/smsgateway.Webhook" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } }, "post": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Registers webhook. If webhook with same ID already exists, it will be replaced", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User", "Webhooks" ], "summary": "Register webhook", "parameters": [ { "description": "Webhook", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/smsgateway.Webhook" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/smsgateway.Webhook" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/3rdparty/v1/webhooks/{id}": { "delete": { "security": [ { "ApiAuth": [] }, { "JWTAuth": [] } ], "description": "Deletes webhook", "produces": [ "application/json" ], "tags": [ "User", "Webhooks" ], "summary": "Delete webhook", "parameters": [ { "type": "string", "description": "Webhook ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully removed" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/smsgateway.ErrorResponse" } } } } }, "/health/live": { "get": { "description": "Checks if service is running (liveness probe)", "produces": [ "application/json" ], "tags": [ "System" ], "summary": "Liveness probe", "responses": { "200": { "description": "Service is alive", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } }, "503": { "description": "Service is not alive", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } } } } }, "/health/ready": { "get": { "description": "Checks if service is ready to serve traffic (readiness probe)", "produces": [ "application/json" ], "tags": [ "System" ], "summary": "Readiness probe", "responses": { "200": { "description": "Service is ready", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } }, "503": { "description": "Service is not ready", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } } } } }, "/health/startup": { "get": { "description": "Checks if service has completed initialization (startup probe)", "produces": [ "application/json" ], "tags": [ "System" ], "summary": "Startup probe", "responses": { "200": { "description": "Service has completed initialization", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } }, "503": { "description": "Service has not completed initialization", "schema": { "$ref": "#/definitions/smsgateway.HealthResponse" } } } } } }, "definitions": { "smsgateway.DataMessage": { "type": "object", "required": [ "data", "port" ], "properties": { "data": { "description": "Data is the base64-encoded payload.", "type": "string", "format": "byte", "maxLength": 65535, "minLength": 4, "example": "SGVsbG8gV29ybGQh" }, "port": { "description": "Port is the destination port.", "type": "integer", "maximum": 65535, "minimum": 1, "example": 53739 } } }, "smsgateway.Device": { "type": "object", "properties": { "createdAt": { "description": "Time at which the device was created, read only.", "type": "string", "example": "2020-01-01T00:00:00Z" }, "deletedAt": { "description": "Time at which the device was deleted, read only.", "type": "string", "example": "2020-01-01T00:00:00Z" }, "id": { "description": "Device ID, read only.", "type": "string", "example": "PyDmBQZZXYmyxMwED8Fzy" }, "lastSeen": { "description": "Time at which the device was last seen, read only.", "type": "string", "example": "2020-01-01T00:00:00Z" }, "name": { "description": "Device name.", "type": "string", "example": "My Device" }, "simCards": { "description": "List of SIM cards in the device.", "type": "array", "items": { "$ref": "#/definitions/smsgateway.SimCard" } }, "updatedAt": { "description": "Time at which the device was last updated, read only.", "type": "string", "example": "2020-01-01T00:00:00Z" } } }, "smsgateway.DeviceSettings": { "type": "object", "properties": { "encryption": { "description": "Encryption contains settings related to message encryption.", "allOf": [ { "$ref": "#/definitions/smsgateway.SettingsEncryption" } ] }, "gateway": { "description": "Gateway contains settings related to the gateway.", "allOf": [ { "$ref": "#/definitions/smsgateway.SettingsGateway" } ] }, "logs": { "description": "Logs contains settings related to logging.", "allOf": [ { "$ref": "#/definitions/smsgateway.SettingsLogs" } ] }, "messages": { "description": "Messages contains settings related to message handling.", "allOf": [ { "$ref": "#/definitions/smsgateway.SettingsMessages" } ] }, "ping": { "description": "Ping contains settings related to ping functionality.", "allOf": [ { "$ref": "#/definitions/smsgateway.SettingsPing" } ] }, "receiver": { "description": "Receiver contains settings related to SMS message reception.", "allOf": [ { "$ref": "#/definitions/smsgateway.SettingsReceiver" } ] }, "webhooks": { "description": "Webhooks contains settings related to webhook functionality.", "allOf": [ { "$ref": "#/definitions/smsgateway.SettingsWebhooks" } ] } } }, "smsgateway.ErrorResponse": { "type": "object", "properties": { "code": { "description": "Error code", "type": "integer" }, "data": { "description": "Error context" }, "message": { "description": "Error message", "type": "string", "example": "An error occurred" } } }, "smsgateway.GetMessageResponse": { "type": "object", "required": [ "deviceId", "id", "recipients", "state" ], "properties": { "dataMessage": { "description": "Present only when `includeContent=true` and the message type is data.", "allOf": [ { "$ref": "#/definitions/smsgateway.DataMessage" } ] }, "deviceId": { "description": "Device ID", "type": "string", "maxLength": 21, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "hashedMessage": { "description": "Hashed message content, if isHashed is true", "allOf": [ { "$ref": "#/definitions/smsgateway.HashedMessage" } ] }, "id": { "description": "Message ID", "type": "string", "maxLength": 36, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "isEncrypted": { "description": "Encrypted", "type": "boolean", "example": false }, "isHashed": { "description": "Hashed", "type": "boolean", "example": false }, "recipients": { "description": "Recipients states", "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/smsgateway.RecipientState" } }, "state": { "description": "State", "allOf": [ { "$ref": "#/definitions/smsgateway.ProcessingState" } ], "example": "Pending" }, "states": { "description": "History of states", "type": "object", "additionalProperties": { "type": "string" } }, "textMessage": { "description": "Present only when `includeContent=true` and the message type is text.", "allOf": [ { "$ref": "#/definitions/smsgateway.TextMessage" } ] } } }, "smsgateway.HashedMessage": { "type": "object", "required": [ "hash" ], "properties": { "hash": { "type": "string", "example": "1d4b6e3b1b6e3b1b6e3b1b6e3b1b6e3b1b6e3b1b" } } }, "smsgateway.HealthCheck": { "type": "object", "properties": { "description": { "description": "A human-readable description of the check.", "type": "string" }, "observedUnit": { "description": "Unit of measurement for the observed value.", "type": "string" }, "observedValue": { "description": "Observed value of the check.", "type": "integer" }, "status": { "description": "Status of the check.\nIt can be one of the following values: \"pass\", \"warn\", or \"fail\".", "allOf": [ { "$ref": "#/definitions/smsgateway.HealthStatus" } ] } } }, "smsgateway.HealthChecks": { "type": "object", "additionalProperties": { "$ref": "#/definitions/smsgateway.HealthCheck" } }, "smsgateway.HealthResponse": { "type": "object", "properties": { "checks": { "description": "A map of check names to their respective details.", "allOf": [ { "$ref": "#/definitions/smsgateway.HealthChecks" } ] }, "releaseId": { "description": "Release ID of the application.\nIt is used to identify the version of the application.", "type": "integer" }, "status": { "description": "Overall status of the application.\nIt can be one of the following values: \"pass\", \"warn\", or \"fail\".", "allOf": [ { "$ref": "#/definitions/smsgateway.HealthStatus" } ] }, "version": { "description": "Version of the application.", "type": "string" } } }, "smsgateway.HealthStatus": { "type": "string", "enum": [ "pass", "warn", "fail" ], "x-enum-varnames": [ "HealthStatusPass", "HealthStatusWarn", "HealthStatusFail" ] }, "smsgateway.InboxRefreshRequest": { "type": "object", "required": [ "since", "until" ], "properties": { "deviceId": { "description": "ID of the device to refresh messages for.", "type": "string", "maxLength": 21, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "messageTypes": { "description": "List of message types to refresh. By default, SMS messages are refreshed.", "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/smsgateway.IncomingMessageType" } }, "since": { "description": "Start of the time range to refresh.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "triggerWebhooks": { "description": "Indicates whether to trigger webhooks for the refreshed messages.", "type": "boolean", "example": true }, "until": { "description": "End of the time range to refresh.", "type": "string", "format": "date-time", "example": "2024-01-01T23:59:59Z" } } }, "smsgateway.IncomingMessage": { "type": "object", "required": [ "contentPreview", "createdAt", "id", "sender", "type" ], "properties": { "contentPreview": { "description": "Message body preview or metadata", "type": "string", "example": "Hello World!" }, "createdAt": { "description": "Message received timestamp", "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00Z" }, "id": { "description": "Incoming message ID", "type": "string", "example": "PyDmBQZZXYmyxMwED8Fzy" }, "recipient": { "description": "Recipient phone number on the device", "type": "string", "example": "+79990001234" }, "sender": { "description": "Incoming sender phone number", "type": "string", "example": "+79990001234" }, "simNumber": { "description": "SIM slot number", "type": "integer", "example": 1 }, "type": { "description": "Message type", "allOf": [ { "$ref": "#/definitions/smsgateway.IncomingMessageType" } ], "example": "SMS" } } }, "smsgateway.IncomingMessageType": { "type": "string", "enum": [ "SMS", "DATA_SMS", "MMS", "MMS_DOWNLOADED" ], "x-enum-comments": { "IncomingMessageTypeDataSMS": "Data SMS message", "IncomingMessageTypeMMS": "MMS message", "IncomingMessageTypeMmsDownloaded": "Downloaded MMS message", "IncomingMessageTypeSMS": "SMS message" }, "x-enum-descriptions": [ "SMS message", "Data SMS message", "MMS message", "Downloaded MMS message" ], "x-enum-varnames": [ "IncomingMessageTypeSMS", "IncomingMessageTypeDataSMS", "IncomingMessageTypeMMS", "IncomingMessageTypeMmsDownloaded" ] }, "smsgateway.JWTScope": { "type": "string", "enum": [ "devices:list", "devices:delete", "inbox:list", "inbox:refresh", "logs:read", "messages:cancel", "messages:send", "messages:read", "messages:list", "messages:export", "settings:read", "settings:write", "tokens:manage", "webhooks:list", "webhooks:write", "webhooks:delete" ], "x-enum-varnames": [ "ScopeDevicesList", "ScopeDevicesDelete", "ScopeInboxList", "ScopeInboxRefresh", "ScopeLogsRead", "ScopeMessagesCancel", "ScopeMessagesSend", "ScopeMessagesRead", "ScopeMessagesList", "ScopeMessagesExport", "ScopeSettingsRead", "ScopeSettingsWrite", "ScopeTokensManage", "ScopeWebhooksList", "ScopeWebhooksWrite", "ScopeWebhooksDelete" ] }, "smsgateway.LimitPeriod": { "type": "string", "enum": [ "Disabled", "PerMinute", "Per30Minutes", "PerHour", "PerDay" ], "x-enum-varnames": [ "Disabled", "PerMinute", "Per30Minutes", "PerHour", "PerDay" ] }, "smsgateway.LogEntry": { "type": "object", "properties": { "context": { "description": "Additional context information related to the log entry, typically including data relevant to the log event.", "type": "object", "additionalProperties": {} }, "createdAt": { "description": "The timestamp when this log entry was created.", "type": "string", "format": "date-time" }, "id": { "description": "A unique identifier for the log entry.", "type": "integer" }, "message": { "description": "A message describing the log event.", "type": "string" }, "module": { "description": "The module or component of the system that generated the log entry.", "type": "string" }, "priority": { "description": "The priority level of the log entry.", "allOf": [ { "$ref": "#/definitions/smsgateway.LogEntryPriority" } ] } } }, "smsgateway.LogEntryPriority": { "type": "string", "enum": [ "DEBUG", "INFO", "WARN", "ERROR" ], "x-enum-varnames": [ "LogEntryPriorityDebug", "LogEntryPriorityInfo", "LogEntryPriorityWarn", "LogEntryPriorityError" ] }, "smsgateway.Message": { "type": "object", "required": [ "phoneNumbers" ], "properties": { "dataMessage": { "description": "Data message", "allOf": [ { "$ref": "#/definitions/smsgateway.DataMessage" } ] }, "deviceId": { "description": "Optional device ID for explicit selection", "type": "string", "maxLength": 21, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "id": { "description": "ID (if not set - will be generated)", "type": "string", "maxLength": 36, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "isEncrypted": { "description": "Is encrypted", "type": "boolean", "example": true }, "message": { "description": "Message content (deprecated, use TextMessage instead)", "type": "string", "maxLength": 65535, "example": "Hello World!" }, "phoneNumbers": { "description": "Recipients (phone numbers)", "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "string" }, "example": [ "79990001234" ] }, "priority": { "description": "Priority, messages with values greater than `99` will bypass limits and delays", "default": 0, "maximum": 127, "minimum": -128, "allOf": [ { "$ref": "#/definitions/smsgateway.MessagePriority" } ], "example": 0 }, "scheduleAt": { "description": "Schedule message delivery at (must be in the future)", "type": "string", "format": "date-time", "example": "2020-01-01T08:30:00Z" }, "simNumber": { "description": "SIM card number (1-3), if not set - default SIM will be used", "type": "integer", "maximum": 3, "minimum": 1, "example": 1 }, "textMessage": { "description": "Text message", "allOf": [ { "$ref": "#/definitions/smsgateway.TextMessage" } ] }, "ttl": { "description": "Time to live in seconds (conflicts with `ValidUntil`)", "type": "integer", "minimum": 5, "example": 86400 }, "validUntil": { "description": "Valid until (conflicts with `TTL`)", "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00Z" }, "withDeliveryReport": { "description": "With delivery report", "type": "boolean", "example": true } } }, "smsgateway.MessagePriority": { "type": "integer", "format": "int32", "enum": [ -128, 0, 100, 127 ], "x-enum-comments": { "PriorityBypassThreshold": "Threshold at which messages bypass limits and delays" }, "x-enum-descriptions": [ "", "", "Threshold at which messages bypass limits and delays", "" ], "x-enum-varnames": [ "PriorityMinimum", "PriorityDefault", "PriorityBypassThreshold", "PriorityMaximum" ] }, "smsgateway.MessageState": { "type": "object", "required": [ "deviceId", "id", "recipients", "state" ], "properties": { "dataMessage": { "description": "Present only when `includeContent=true` and the message type is data.", "allOf": [ { "$ref": "#/definitions/smsgateway.DataMessage" } ] }, "deviceId": { "description": "Device ID", "type": "string", "maxLength": 21, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "hashedMessage": { "description": "Hashed message content, if isHashed is true", "allOf": [ { "$ref": "#/definitions/smsgateway.HashedMessage" } ] }, "id": { "description": "Message ID", "type": "string", "maxLength": 36, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "isEncrypted": { "description": "Encrypted", "type": "boolean", "example": false }, "isHashed": { "description": "Hashed", "type": "boolean", "example": false }, "recipients": { "description": "Recipients states", "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/smsgateway.RecipientState" } }, "state": { "description": "State", "allOf": [ { "$ref": "#/definitions/smsgateway.ProcessingState" } ], "example": "Pending" }, "states": { "description": "History of states", "type": "object", "additionalProperties": { "type": "string" } }, "textMessage": { "description": "Present only when `includeContent=true` and the message type is text.", "allOf": [ { "$ref": "#/definitions/smsgateway.TextMessage" } ] } } }, "smsgateway.MessagesProcessingOrder": { "type": "string", "enum": [ "LIFO", "FIFO" ], "x-enum-varnames": [ "LIFO", "FIFO" ] }, "smsgateway.ProcessingState": { "type": "string", "enum": [ "Pending", "Cancelling", "Cancelled", "Processed", "Sent", "Delivered", "Failed" ], "x-enum-comments": { "ProcessingStateCancelled": "Cancelled", "ProcessingStateCancelling": "Cancelling (cancellation requested)", "ProcessingStateDelivered": "Delivered", "ProcessingStateFailed": "Failed", "ProcessingStatePending": "Pending", "ProcessingStateProcessed": "Processed (received by device)", "ProcessingStateSent": "Sent" }, "x-enum-descriptions": [ "Pending", "Cancelling (cancellation requested)", "Cancelled", "Processed (received by device)", "Sent", "Delivered", "Failed" ], "x-enum-varnames": [ "ProcessingStatePending", "ProcessingStateCancelling", "ProcessingStateCancelled", "ProcessingStateProcessed", "ProcessingStateSent", "ProcessingStateDelivered", "ProcessingStateFailed" ] }, "smsgateway.RecipientState": { "type": "object", "required": [ "phoneNumber", "state" ], "properties": { "error": { "description": "Error (for `Failed` state)", "type": "string", "example": "timeout" }, "phoneNumber": { "description": "Phone number or first 16 symbols of SHA256 hash", "type": "string", "maxLength": 128, "minLength": 1, "example": "79990001234" }, "state": { "description": "State", "allOf": [ { "$ref": "#/definitions/smsgateway.ProcessingState" } ], "example": "Pending" } } }, "smsgateway.SettingsEncryption": { "type": "object", "properties": { "passphrase": { "description": "Passphrase is the encryption passphrase. If nil or empty, encryption is disabled. Must not be used with Cloud Server.", "type": "string" } } }, "smsgateway.SettingsGateway": { "type": "object", "properties": { "cloud_url": { "description": "CloudURL is the URL of the cloud server. Must not be used with Cloud Server.", "type": "string" }, "notification_channel": { "description": "NotificationChannel is the way device receives notifications.", "type": "string", "enum": [ "AUTO", "SSE_ONLY" ] }, "private_token": { "description": "PrivateToken is the auth token for the private server. Must not be used with Cloud Server.", "type": "string" } } }, "smsgateway.SettingsLogs": { "type": "object", "properties": { "lifetime_days": { "description": "LifetimeDays is the number of days to retain logs.\nMust be at least 1 when provided.", "type": "integer", "minimum": 1 } } }, "smsgateway.SettingsMessages": { "type": "object", "properties": { "limit_period": { "description": "LimitPeriod defines the period for message sending limits.\nValid values are \"Disabled\", \"PerMinute\", \"Per30Minutes\", \"PerHour\", or \"PerDay\".", "enum": [ "Disabled", "PerMinute", "Per30Minutes", "PerHour", "PerDay" ], "allOf": [ { "$ref": "#/definitions/smsgateway.LimitPeriod" } ] }, "limit_value": { "description": "LimitValue is the maximum number of messages allowed per limit period.\nMust be at least 1 when provided.", "type": "integer", "minimum": 1 }, "log_lifetime_days": { "description": "LogLifetimeDays is the number of days to retain message logs.\nMust be at least 1 when provided.", "type": "integer", "minimum": 1 }, "processing_order": { "description": "MessagesProcessingOrder defines the order in which messages are processed.\nValid values are \"LIFO\" or \"FIFO\".", "enum": [ "LIFO", "FIFO" ], "allOf": [ { "$ref": "#/definitions/smsgateway.MessagesProcessingOrder" } ] }, "send_interval_max": { "description": "SendIntervalMax is the maximum interval between message sends (in seconds).\nMust be at least 1 when provided and greater than or equal to SendIntervalMin.", "type": "integer", "minimum": 1 }, "send_interval_min": { "description": "SendIntervalMin is the minimum interval between message sends (in seconds).\nMust be at least 1 when provided.", "type": "integer", "minimum": 1 }, "sim_selection_mode": { "description": "SimSelectionMode defines how SIM cards are selected for sending messages.\nValid values are \"OSDefault\", \"RoundRobin\", or \"Random\".", "enum": [ "OSDefault", "RoundRobin", "Random" ], "allOf": [ { "$ref": "#/definitions/smsgateway.SimSelectionMode" } ] }, "work_hours_enabled": { "description": "WorkHoursEnabled enables restricting message delivery to a configurable time window.", "type": "boolean" }, "work_hours_end": { "description": "WorkHoursEnd is the end of the working hours window in HH:mm format (24-hour).", "type": "string" }, "work_hours_start": { "description": "WorkHoursStart is the start of the working hours window in HH:mm format (24-hour).", "type": "string" } } }, "smsgateway.SettingsPing": { "type": "object", "properties": { "interval_seconds": { "description": "IntervalSeconds is the interval between ping requests (in seconds).\nMust be at least 1 when provided.", "type": "integer", "minimum": 1 } } }, "smsgateway.SettingsReceiver": { "type": "object", "properties": { "content_provider_enabled": { "description": "ContentProviderEnabled enables monitoring the SMS content provider as a fallback for\ncarriers that intercept the SMS_RECEIVED broadcast.", "type": "boolean" } } }, "smsgateway.SettingsWebhooks": { "type": "object", "properties": { "internet_required": { "description": "InternetRequired indicates whether internet access is required for webhooks.", "type": "boolean" }, "retry_count": { "description": "RetryCount is the number of times to retry failed webhook deliveries.\nMust be at least 1 when provided.", "type": "integer", "minimum": 1 }, "signing_key": { "description": "SigningKey is the secret key used for signing webhook payloads. Must not be used with Cloud Server.", "type": "string" } } }, "smsgateway.SimCard": { "type": "object", "properties": { "carrierName": { "description": "Carrier/network operator name (may be null).", "type": "string" }, "iccid": { "description": "Integrated Circuit Card Identifier (may be null).", "type": "string" }, "phoneNumber": { "description": "Phone number associated with the SIM.", "type": "string" }, "simNumber": { "description": "1-based slot number (1, 2, or 3).", "type": "integer" }, "slotIndex": { "description": "0-based physical slot index.", "type": "integer" } } }, "smsgateway.SimSelectionMode": { "type": "string", "enum": [ "OSDefault", "RoundRobin", "Random" ], "x-enum-varnames": [ "OSDefault", "RoundRobin", "Random" ] }, "smsgateway.TextMessage": { "type": "object", "required": [ "text" ], "properties": { "text": { "description": "Text is the message text.", "type": "string", "maxLength": 65535, "minLength": 1, "example": "Hello World!" } } }, "smsgateway.TokenRequest": { "type": "object", "required": [ "scopes" ], "properties": { "scopes": { "description": "scopes for which the access token is valid", "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/smsgateway.JWTScope" } }, "ttl": { "description": "lifetime of the access token in seconds", "type": "integer" } } }, "smsgateway.TokenResponse": { "type": "object", "properties": { "access_token": { "description": "actual access token", "type": "string" }, "expires_at": { "description": "time at which the access token is no longer valid", "type": "string", "format": "date-time" }, "id": { "description": "unique identifier for the access token", "type": "string" }, "refresh_token": { "description": "refresh token", "type": "string" }, "token_type": { "description": "type of the access token", "type": "string" } } }, "smsgateway.Webhook": { "type": "object", "required": [ "event", "url" ], "properties": { "deviceId": { "description": "The unique identifier of the device the webhook is associated with.", "type": "string", "maxLength": 21, "example": "PyDmBQZZXYmyxMwED8Fzy" }, "event": { "description": "The type of event the webhook is triggered for.", "allOf": [ { "$ref": "#/definitions/smsgateway.WebhookEvent" } ], "example": "sms:received" }, "id": { "description": "The unique identifier of the webhook.", "type": "string", "maxLength": 36, "example": "123e4567-e89b-12d3-a456-426614174000" }, "url": { "description": "The URL the webhook will be sent to.", "type": "string", "example": "https://example.com/webhook" } } }, "smsgateway.WebhookEvent": { "type": "string", "enum": [ "sms:received", "sms:data-received", "sms:sent", "sms:delivered", "sms:failed", "sms:cancelled", "system:ping", "mms:received", "mms:downloaded", "app:started" ], "x-enum-comments": { "WebhookEventAppStarted": "Triggered when the application is started.", "WebhookEventMmsDownloaded": "Triggered when an MMS is downloaded.", "WebhookEventMmsReceived": "Triggered when an MMS is received.", "WebhookEventSmsCancelled": "Triggered when an SMS is cancelled.", "WebhookEventSmsDataReceived": "Triggered when a data SMS is received.", "WebhookEventSmsDelivered": "Triggered when an SMS is delivered.", "WebhookEventSmsFailed": "Triggered when an SMS processing fails.", "WebhookEventSmsReceived": "Triggered when an SMS is received.", "WebhookEventSmsSent": "Triggered when an SMS is sent.", "WebhookEventSystemPing": "Triggered when the device pings the server." }, "x-enum-descriptions": [ "Triggered when an SMS is received.", "Triggered when a data SMS is received.", "Triggered when an SMS is sent.", "Triggered when an SMS is delivered.", "Triggered when an SMS processing fails.", "Triggered when an SMS is cancelled.", "Triggered when the device pings the server.", "Triggered when an MMS is received.", "Triggered when an MMS is downloaded.", "Triggered when the application is started." ], "x-enum-varnames": [ "WebhookEventSmsReceived", "WebhookEventSmsDataReceived", "WebhookEventSmsSent", "WebhookEventSmsDelivered", "WebhookEventSmsFailed", "WebhookEventSmsCancelled", "WebhookEventSystemPing", "WebhookEventMmsReceived", "WebhookEventMmsDownloaded", "WebhookEventAppStarted" ] } }, "securityDefinitions": { "ApiAuth": { "type": "basic" }, "JWTAuth": { "description": "JWT authentication", "type": "apiKey", "name": "Authorization", "in": "header" }, "MobileToken": { "description": "Mobile device token", "type": "apiKey", "name": "Authorization", "in": "header" }, "ServerKey": { "description": "Private server authentication", "type": "apiKey", "name": "Authorization", "in": "header" }, "UserCode": { "description": "User one-time code authentication", "type": "apiKey", "name": "Authorization", "in": "header" } } }