{ "openapi": "3.1.1", "info": { "title": "Ting API", "description": "API สำหรับ backend ของลูกค้า — ส่งแจ้งเตือน, ติดตามสถานะการส่ง, อัปโหลดสื่อ และจัดการผู้ติดตาม ทุก endpoint ยืนยันตัวตนด้วย API token ของแอป (header `X-Ting-Api-Token`, ค่าขึ้นต้นด้วย `tapp_`) ซึ่งสร้างได้ที่หน้ารายละเอียดแอปในคอนโซล\n\nคู่มือฉบับเต็มพร้อมตัวอย่างโค้ด 8 ภาษา และหัวข้อที่ไม่ใช่ REST (Events Webhook, Command Ting, Pages): https://ting.mawin.one/api-reference", "version": "v1" }, "servers": [ { "url": "https://api.mawin.one", "description": "Ting API" } ], "paths": { "/api/apps/{code}/media": { "post": { "tags": [ "Media" ], "summary": "Upload media", "description": "อัปโหลดรูป/วิดีโอ/ไฟล์ให้ Ting เก็บไว้ แล้วนำ mediaUrl ที่ได้ไปใส่ในคำขอ notify — multipart/form-data: type = image | video | file, file = ไฟล์", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string" } } }, { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/IFormFile" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/MediaUploadResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/MediaUploadResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } }, "/api/apps/v1/join-pins": { "post": { "tags": [ "Join" ], "summary": "Generate a join PIN", "description": "สร้างรหัส PIN สำหรับเข้าร่วมแอปที่ตั้งเป็นห้องส่วนตัว — ใช้ได้ครั้งเดียว อายุ 24 ชั่วโมง สร้างพร้อมกันหลายรหัสได้ รหัสเดิมที่ยังไม่หมดอายุไม่ถูกยกเลิก ใช้เมื่อระบบของคุณต้องการแจกรหัสให้ลูกค้าเองโดยไม่ต้องเข้าหน้าคอนโซล Ting", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/JoinPinListItemResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/JoinPinListItemResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/JoinPinListItemResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } }, "/api/apps/v1/notify": { "post": { "tags": [ "Notify" ], "summary": "Send a notification", "description": "endpoint หลัก — ส่งข้อความ (พร้อมสื่อ/ปุ่ม/การ์ด HTML) ไปยังผู้ติดตามผ่านช่องทางที่เชื่อมไว้ (LINE, Telegram, Discord, Slack, Messenger, Instagram, WhatsApp, Ting App) งานเข้าคิวแล้วคืน id ทันที ตามผลได้ที่ GET /api/apps/v1/sends/{id}", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendNotificationRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SendNotificationRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SendNotificationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/QueuedNotificationResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/QueuedNotificationResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/QueuedNotificationResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } }, "/api/apps/v1/sends/{id}/message": { "patch": { "tags": [ "Sends" ], "summary": "Edit a sent message", "description": "แก้ข้อความที่ส่งไปแล้ว โดยอ้างจาก id ที่ได้ตอนส่ง — มีผลกับผู้รับทุกคนของงานส่งนั้น (รวม broadcast) และมีผลเฉพาะแอป Ting เท่านั้น ข้อความที่ส่งออกไปยัง LINE/Telegram/ช่องทางอื่นแก้ไม่ได้ เวอร์ชันก่อนหน้าถูกเก็บไว้และผู้ใช้กดดูย้อนหลังได้ในแอป", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditSentMessageRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EditSentMessageRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/EditSentMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EditSentMessageResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EditSentMessageResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EditSentMessageResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } }, "/api/apps/v1/sends/{id}": { "get": { "tags": [ "Sends" ], "summary": "Get send status", "description": "สถานะของงานส่งหนึ่งงาน (QUEUED / SENDING / SENT / PARTIAL / FAILED) พร้อมจำนวนสำเร็จ/ล้มเหลวและรายละเอียดต่อช่องทาง", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/SendStatusResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SendStatusResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SendStatusResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } }, "/api/apps/v1/sends": { "get": { "tags": [ "Sends" ], "summary": "List sends", "description": "รายการงานส่งของแอป เรียงล่าสุดก่อน แบ่งหน้า — กรองตามสถานะ/ช่วงเวลาได้", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PagedSendStatusResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PagedSendStatusResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PagedSendStatusResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } }, "/api/apps/{code}/channels/{channel}/subscribers": { "get": { "tags": [ "Subscribers" ], "summary": "List subscribers", "description": "ผู้ติดตามของช่องทางหนึ่ง (channel = LINE, TELEGRAM, DISCORD, SLACK, MESSENGER, INSTAGRAM, WHATSAPP, TING) แบ่งหน้า ค้นหาได้", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PagedChannelSubscribersResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PagedChannelSubscribersResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PagedChannelSubscribersResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } }, "/api/apps/{code}/channels/{channel}/subscribers/{externalId}": { "get": { "tags": [ "Subscribers" ], "summary": "Get a subscriber", "description": "ข้อมูลผู้ติดตามคนเดียว ระบุด้วย externalId ของช่องทางนั้น (เช่น LINE userId, Telegram chat id, รหัส Ting)", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ChannelSubscriberResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ChannelSubscriberResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChannelSubscriberResponse" } } } } }, "security": [ { "AppToken": [ ] } ] }, "put": { "tags": [ "Subscribers" ], "summary": "Update a subscriber", "description": "แก้ชื่อที่แสดง / แท็ก / วันหมดอายุ / บันทึกของผู้ติดตาม", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriberRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriberRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriberRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ChannelSubscriberResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ChannelSubscriberResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChannelSubscriberResponse" } } } } }, "security": [ { "AppToken": [ ] } ] } } }, "components": { "schemas": { "ChannelSubscriberResponse": { "type": "object", "properties": { "externalId": { "type": "string" }, "displayName": { "type": [ "null", "string" ] }, "sourceType": { "type": "string" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time" }, "isExpired": { "type": "boolean" } } }, "EditSentMessageRequest": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string" } } }, "EditSentMessageResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "updatedCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "editedAt": { "type": "string", "format": "date-time" } } }, "IFormFile": { "type": "string", "format": "binary" }, "JoinPinListItemResponse": { "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "pin": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } }, "MediaUploadResponse": { "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "url": { "type": "string" }, "mediaType": { "type": "string" }, "width": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "height": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "fileSizeBytes": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "PagedChannelSubscribersResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelSubscriberResponse" } }, "totalCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "pageSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "PagedSendStatusResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SendStatusListItem" } }, "totalCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "pageSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "QueuedNotificationResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "sendLogId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" } } }, "SendNotificationRequest": { "type": "object", "properties": { "message": { "type": "string" }, "subject": { "type": [ "null", "string" ] }, "channels": { "type": [ "null", "array" ], "items": { "type": "string" } }, "broadcast": { "type": [ "null", "boolean" ] }, "replyToken": { "type": [ "null", "string" ] }, "recipients": { "type": [ "null", "object" ], "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "tags": { "type": [ "null", "array" ], "items": { "type": "string" } }, "agent": { "type": [ "null", "string" ] }, "includeExpired": { "type": "boolean" }, "delaySeconds": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "page": { "type": [ "null", "string" ] }, "pageHeight": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "mediaUrl": { "type": [ "null", "string" ] }, "mediaType": { "type": [ "null", "string" ] } } }, "SendStatusChannel": { "type": "object", "properties": { "channelType": { "type": "string" }, "channelName": { "type": "string" }, "status": { "type": "string" }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "processed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "sent": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "failed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "failureReason": { "type": [ "null", "string" ] }, "startedAt": { "type": [ "null", "string" ], "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "format": "date-time" }, "failures": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/SendStatusRecipient" } } } }, "SendStatusListItem": { "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "status": { "type": "string" }, "done": { "type": "boolean" }, "error": { "type": [ "null", "string" ] }, "source": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "format": "date-time" }, "summary": { "$ref": "#/components/schemas/SendStatusSummary" } } }, "SendStatusRecipient": { "type": "object", "properties": { "externalId": { "type": "string" }, "displayName": { "type": [ "null", "string" ] }, "detail": { "type": [ "null", "string" ] } } }, "SendStatusResponse": { "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "status": { "type": "string" }, "done": { "type": "boolean" }, "error": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "null", "string" ], "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "format": "date-time" }, "summary": { "$ref": "#/components/schemas/SendStatusSummary" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/SendStatusChannel" } } } }, "SendStatusSummary": { "type": "object", "properties": { "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "sent": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "failed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "pending": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "UpdateSubscriberRequest": { "type": "object", "properties": { "tags": { "type": [ "null", "array" ], "items": { "type": "string" } }, "status": { "type": [ "null", "string" ] }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time" }, "clearExpiresAt": { "type": "boolean" } } } }, "securitySchemes": { "AppToken": { "type": "apiKey", "description": "API token ของแอป (ขึ้นต้นด้วย tapp_) — สร้าง/ดูได้ที่หน้ารายละเอียดแอป → API token", "name": "X-Ting-Api-Token", "in": "header" } } }, "security": [ { "AppToken": [ ] } ], "tags": [ { "name": "Media" }, { "name": "Join" }, { "name": "Notify" }, { "name": "Sends" }, { "name": "Subscribers" } ] }