{ "openapi": "3.0.3", "info": { "title": "Tilefin WhatsApp API", "version": "1.0.0", "description": "Standalone prepaid API by TILEFIN IT SOLUTIONS (OPC) PRIVATE LIMITED. See README for integration boundaries." }, "servers": [ { "url": "/" } ], "paths": { "/api/v1/channels": { "post": { "operationId": "createChannel", "summary": "create Channel", "description": "Required scope: channels:write", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Channel" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelInput" } } } } }, "get": { "operationId": "listChannels", "summary": "list Channels", "description": "Required scope: channels:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/channels/{channel}": { "get": { "operationId": "getChannel", "summary": "get Channel", "description": "Required scope: channels:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "channel", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Channel" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/channels/{channel}/onboarding": { "post": { "operationId": "beginOnboarding", "summary": "begin Onboarding", "description": "Required scope: channels:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "channel", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Onboarding" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/channels/{channel}/onboarding-status": { "get": { "operationId": "getOnboardingStatus", "summary": "get Onboarding Status", "description": "Required scope: channels:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "channel", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OnboardingStatus" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/templates": { "get": { "operationId": "listTemplates", "summary": "list Templates", "description": "Required scope: templates:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "channel_id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTemplate", "summary": "create Template", "description": "Required scope: templates:write", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Template" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } } } }, "/api/v1/templates/{template}": { "get": { "operationId": "getTemplate", "summary": "get Template", "description": "Required scope: templates:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Template" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages": { "post": { "operationId": "sendMessage", "summary": "send Message", "description": "Required scope: messages:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Message" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient prepaid balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } } }, "get": { "operationId": "listMessages", "summary": "list Messages", "description": "Required scope: messages:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{message}": { "get": { "operationId": "getMessage", "summary": "get Message", "description": "Required scope: messages:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "message", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Message" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/wallet": { "get": { "operationId": "getWallet", "summary": "get Wallet", "description": "Required scope: wallet:read", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Wallet" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/usage": { "get": { "operationId": "getUsage", "summary": "get Usage", "description": "Required scope: usage:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string" } }, { "in": "query", "name": "to", "schema": { "type": "string" } }, { "in": "query", "name": "channel_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Usage" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "get Health", "description": "Public health check", "security": [], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Health" } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/webhooks/providers/gupshup": { "post": { "operationId": "receiveProviderEvent", "summary": "receive Provider Event", "description": "Trusted gateway HMAC required; not a native Gupshup signature.", "security": [], "parameters": [ { "in": "header", "name": "X-Tilefin-Gateway-Timestamp", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Tilefin-Gateway-Signature", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "ignored": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } } }, "500": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See errors.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderEvent" } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "tf_live_ API key" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "ChannelInput": { "type": "object", "properties": { "business_name": { "type": "string", "maxLength": 200 }, "external_id": { "type": "string", "maxLength": 200 } }, "required": [ "business_name" ] }, "Channel": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "business_name": { "type": "string" }, "external_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "display_phone_masked": { "type": "string", "nullable": true }, "onboarding_status": { "type": "string", "nullable": true } } }, "TemplateInput": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "pattern": "^[a-z0-9_]+$", "maxLength": 100 }, "language": { "type": "string", "maxLength": 20 }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "components": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BODY" ] }, "text": { "type": "string", "maxLength": 1024 }, "example": { "type": "string", "maxLength": 1024 } }, "required": [ "type", "text" ], "additionalProperties": false } } }, "required": [ "channel_id", "name", "language", "category", "components" ] }, "Template": { "type": "object", "properties": { "template_id": { "type": "string", "format": "uuid" }, "channel_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "language": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "APPROVED", "REJECTED", "PAUSED", "DISABLED" ] }, "requested_category": { "type": "string" }, "approved_category": { "type": "string", "nullable": true }, "components": { "type": "array", "items": { "type": "object" } }, "submission_error": { "type": "string" }, "rejection_reason": { "type": "string", "nullable": true } } }, "MessageInput": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "to": { "type": "string", "maxLength": 30 }, "client_reference": { "type": "string", "maxLength": 200 }, "template": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 20 }, "parameters": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 1024 } } }, "required": [ "name", "language", "parameters" ], "additionalProperties": false } }, "required": [ "channel_id", "to", "template" ] }, "Message": { "type": "object", "properties": { "message_id": { "type": "string", "format": "uuid" }, "channel_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "submitted", "sent", "delivered", "read", "failed" ] }, "client_reference": { "type": "string", "nullable": true }, "destination_masked": { "type": "string" }, "category": { "type": "string" }, "client_price": { "type": "string" }, "currency": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Wallet": { "type": "object", "properties": { "balance": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" } } }, "Usage": { "type": "object", "properties": { "total_messages": { "type": "integer" }, "utility": { "type": "integer" }, "marketing": { "type": "integer" }, "authentication": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "total_charged": { "type": "string" }, "total_reserved": { "type": "string" }, "current_wallet_balance": { "type": "string" }, "currency": { "type": "string" } } }, "Health": { "type": "object", "properties": { "api": { "type": "string" }, "db": { "type": "string" }, "queue": { "type": "string" }, "provider_configured": { "type": "boolean" } } }, "Onboarding": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "OnboardingStatus": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "onboarding_status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProviderEvent": { "type": "object", "properties": { "app": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "message-event" ] }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "gsId": { "type": "string" }, "type": { "type": "string", "enum": [ "enqueued", "sent", "delivered", "read", "failed" ] }, "payload": { "type": "object" } } } }, "required": [ "app", "timestamp", "type", "payload" ] }, "ClientWebhook": { "type": "object", "properties": { "event": { "type": "string" }, "event_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "channel_id": { "type": "string", "format": "uuid" }, "client_reference": { "type": "string", "nullable": true }, "status": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }