{ "openapi": "3.1.0", "info": { "title": "NextSMS Messaging API v2", "version": "2.0", "description": "Version 2: send SMS, Mobile SMS and WhatsApp template messages, check balance and read delivery reports, signing in with an API token (Bearer).\n\nRules: always send 'Accept: application/json'. Phone numbers are 255XXXXXXXXX without '+'. messageId is a 64-bit integer; keep it as a string. Dates are YYYY-MM-DD and times HH:MM in East Africa Time (UTC+3). Use the /test/ endpoints to validate a send without sending or charging.\n\nHuman guide: https://nextsms.co.tz/api-docs — Postman collection: https://documenter.getpostman.com/view/1679195/2sAYkDP1XN" }, "externalDocs": { "description": "Postman documentation", "url": "https://documenter.getpostman.com/view/1679195/2sAYkDP1XN" }, "servers": [ { "url": "https://messaging-service.co.tz" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "account", "description": "Account" }, { "name": "send", "description": "Send messages" }, { "name": "test", "description": "Test without sending" }, { "name": "reports", "description": "Reports & logs" } ], "paths": { "/api/v2/balance": { "get": { "operationId": "balance_v2", "tags": [ "account" ], "summary": "Check your balance", "description": "Returns your available balance. Call it before a big campaign to make sure you have enough credit.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "sms_balance": 125000.5, "over_draft": 0, "type": "price", "default_balance": 6250, "default": "Internet Channel", "display": "125,000.5 TZS" } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/{channel}/v2/text/single": { "post": { "operationId": "send_single_v2", "tags": [ "send" ], "summary": "Send a message (SMS or Mobile SMS)", "description": "The endpoint most people need. Put one number or a list of numbers in \"to\", your Sender ID in \"from\" and the message in \"text\". Every number gets the same text. To send different texts in one request, use \"Send different messages in one request\".\n\n- A 200 response means the request was processed. Check the status of every number in \"messages\": numbers that were rejected have status groupName \"REJECTED\" and no messageId.\n- Scheduled messages (with date and time) are accepted with status ACCEPTED and charged when they are sent.\n- If your balance runs out part way, the remaining numbers get FAILED_NOT_ENOUGH_CREDITS and the rest are still sent.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Where to send: sms, mobile or whatsapp. See \"Channels\".", "schema": { "type": "string", "enum": [ "sms", "mobile", "whatsapp" ] }, "example": "sms" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "messages": [ { "to": "255712345678", "status": { "groupId": 18, "groupName": "PENDING", "id": 51, "name": "ENROUTE (SENT)", "description": "Message sent to next instance" }, "messageId": 7391827364512378881, "message": "Hello! Your order 1001 is ready for pickup.", "smsCount": 1, "price": 20 } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "examples": [ "NEXTSMS" ], "description": "Your approved Sender ID, exactly as registered (capital letters matter). Ignored for mobile. (Required for sms.)" }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "examples": [ [ "255712345678", "255754000111" ] ], "description": "One phone number, or a list of numbers. Use 255XXXXXXXXX (no + sign). Local formats such as 0712345678 also work here. Repeated numbers are sent once." }, "text": { "type": "string", "examples": [ "Hello! Your order 1001 is ready for pickup." ], "description": "The message. Long texts are split into parts (see \"Count SMS parts\")." }, "reference": { "type": "string", "examples": [ "order-1001" ], "description": "Your own label for this send (up to 50 characters, no spaces). Use it later to find these messages in reports and logs." }, "flash": { "type": "integer", "examples": [ 0 ], "description": "1 = flash SMS (pops up on the screen and is not saved in the inbox). 0 = normal SMS. Leave it out for normal SMS." }, "country": { "type": "string", "examples": [ "TZ" ], "description": "Two-letter country code used to understand local number formats. Default TZ." }, "date": { "type": "string", "examples": [ "2026-12-01" ], "description": "Send later on this date, format YYYY-MM-DD (East Africa Time). Must be today or later. (Required with time.)" }, "time": { "type": "string", "examples": [ "08:30" ], "description": "Send later at this time, 24-hour format HH:MM (East Africa Time, UTC+3). (Required with date.)" }, "repeat": { "type": "string", "examples": [ "weekly" ], "description": "Repeat the scheduled message: daily, weekly, monthly or yearly. Send it together with date, time, start_date and end_date. (Required for repeating.)" }, "start_date": { "type": "string", "examples": [ "2026-12-01" ], "description": "First day of the repeat period, YYYY-MM-DD. Not before date. (Required for repeating.)" }, "end_date": { "type": "string", "examples": [ "2027-03-01" ], "description": "Last day of the repeat period, YYYY-MM-DD. Not before start_date. (Required for repeating.)" } }, "required": [ "to", "text" ] }, "example": { "from": "NEXTSMS", "to": [ "255712345678", "255754000111" ], "text": "Hello! Your order 1001 is ready for pickup.", "reference": "order-1001" } } } } } }, "/api/whatsapp/v2/text/single": { "post": { "operationId": "send_whatsapp_v2", "tags": [ "send" ], "summary": "Send a WhatsApp template message", "description": "WhatsApp business messages must use a template that Meta has approved. You choose the template by name, and give the values for its {placeholders} for each recipient, in the same order as \"to\".\n\n- Only send the header and button parts your template actually has: a template has at most one header (image, document, location or text). \"All fields\" below shows every possible part at once, for reference only.\n- Every per-recipient list (personalisation, header.images, header.documents and each \"parameters\" list) must have one entry per number in \"to\", in the same order.\n- \"message\" in the response is the template text with its {placeholders}; each person receives their own values.\n- A WhatsApp message can produce several delivery callbacks: SENT, then DELIVERED, then READ.\n- Older field names (media.document, media.document_name) still work, but use header for new integrations.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "messages": [ { "to": "255712345678", "status": { "groupId": 18, "groupName": "PENDING", "id": 51, "name": "ENROUTE (SENT)", "description": "Message sent to next instance" }, "messageId": 7391827364512378881, "message": "Hi {name}, your order {order} has been shipped.", "smsCount": 1, "price": 50 } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "examples": [ "MyShop" ], "description": "The name of your active WhatsApp account, as shown under WhatsApp → Accounts." }, "template": { "type": "string", "examples": [ "order_update" ], "description": "The name of an active, approved template." }, "to": { "type": "array", "examples": [ [ 255712345678, 255754000111 ] ], "description": "List of WhatsApp numbers as numbers (not text), for example [255712345678]. Every per-recipient list below follows this order." }, "personalisation": { "type": "array", "examples": [ [ { "name": "Asha", "order": "A12" }, { "name": "John", "order": "B7" } ] ], "description": "One object per recipient, in \"to\" order. Keys are the body placeholders without braces, e.g. {\"name\": \"Asha\", \"number\": \"123456\"} for \"Hi {name}, your order {number}…\". No value may be empty. (Required if the template body has {placeholders}.)" }, "header": { "type": "object", "description": "header.image: One image for every recipient. Use header.images instead to give each recipient their own image; do not send both. (Required if the template header is an image.)\nheader.image.file: A public https link to the image, or base64 data. PNG or JPEG, up to 3 MB. (Required with header.image.)\nheader.image.name: Optional file name for the image. Can be empty.\nheader.image.personalisation.qr_code_url: Draws a QR code on the image for each recipient, e.g. an event ticket. The QR code holds the template's QR link with {par} replaced by that recipient's value. All four fields below are required. (Required if the template prints a QR code on the image.)\nheader.image.personalisation.qr_code_url.x_start: Left edge of the QR code, as a percentage (0–100) of the image width. (Required with qr_code_url.)\nheader.image.personalisation.qr_code_url.y_start: Top edge of the QR code, as a percentage (0–100) of the image height. (Required with qr_code_url.)\nheader.image.personalisation.qr_code_url.size: Width and height of the QR code, as a percentage (0–100) of the image's shorter side. A QR code that would go past the edge is moved inside the image. (Required with qr_code_url.)\nheader.image.personalisation.qr_code_url.parameters: The value put into the QR link for each recipient, in \"to\" order, e.g. their ticket number. (Required with qr_code_url.)\nheader.images: A different image for each recipient, in \"to\" order: [{\"file\": \"...\", \"name\": \"\"}, ...]. Same file rules as header.image.file. The number of entries must equal the number of recipients. (Required for one image per recipient.)\nheader.document: One PDF for every recipient. Use header.documents instead to give each recipient their own PDF; do not send both. (Required if the template header is a document.)\nheader.document.file: A public https link to the PDF, or base64 data. PDF only, up to 1 MB. (Required with header.document.)\nheader.document.name: The file name the recipient sees, e.g. \"Invoice.pdf\".\nheader.document.caption: Optional text shown under the document.\nheader.documents: A different PDF for each recipient, in \"to\" order: [{\"file\": \"...\", \"name\": \"Invoice-Asha.pdf\", \"caption\": \"\"}, ...]. Same rules as header.document. The number of entries must equal the number of recipients. (Required for one document per recipient.)\nheader.location: A map pin shown at the top of the message. All four fields below are required. (Required if the template header is a location.)\nheader.location.latitude: Latitude in decimal degrees. (Required with header.location.)\nheader.location.longitude: Longitude in decimal degrees. (Required with header.location.)\nheader.location.name: Name of the place. (Required with header.location.)\nheader.location.address: Address of the place. (Required with header.location.)\nheader.text.personalisation.parameters: For a text header with a placeholder, e.g. \"Order {par}\": the value for each recipient, in \"to\" order. (Required if the header text has a placeholder.)" }, "button": { "type": "object", "description": "button.personalisation.url_link.parameters: For a \"Visit website\" button whose link ends with a placeholder: the end of the link for each recipient, in \"to\" order. (Required if the link button is dynamic.)\nbutton.personalisation.copy_code.parameters: For a \"Copy offer code\" button (marketing templates): the coupon code each recipient copies, in \"to\" order. (Required if the template has a copy-code button.)\nbutton.personalisation.copy_otp_code.parameters: For a \"Copy code\" button on authentication (one-time password) templates: the OTP code for each recipient, in \"to\" order. (Required if the template has a copy-OTP button.)\nbutton.personalisation.quick_reply.parameters: Optional custom payloads for quick-reply buttons. Keys are the button's position among the quick-reply buttons (\"0\" = first, \"1\" = second, …); each value is a list with one payload per recipient, in \"to\" order. When the person taps that button, the payload comes back to you in the reply callback, so you know who answered what. Without it, the button works with no payload." }, "reference": { "type": "string", "examples": [ "promo-oct" ], "description": "Your own label for this send (up to 50 characters, no spaces)." }, "date": { "type": "string", "examples": [ "2026-12-01" ], "description": "Send later on this date, format YYYY-MM-DD (East Africa Time). Must be today or later. (Required with time.)" }, "time": { "type": "string", "examples": [ "08:30" ], "description": "Send later at this time, 24-hour format HH:MM (East Africa Time, UTC+3). (Required with date.)" } }, "required": [ "account", "template", "to" ] }, "example": { "account": "MyShop", "template": "order_update", "to": [ 255712345678, 255754000111 ], "personalisation": [ { "name": "Asha", "order": "A12" }, { "name": "John", "order": "B7" } ], "header": { "image": { "file": "https://example.com/banner.jpg" } }, "button": { "personalisation": { "url_link": { "parameters": [ "A12", "B7" ] } } } } } } } } }, "/api/{channel}/v2/text/multi": { "post": { "operationId": "send_multi_v2", "tags": [ "send" ], "summary": "Send different messages in one request", "description": "Use this when each person should get their own text, for example \"Hi Asha, your balance is 5,000\". Put up to 500 messages in the \"messages\" list. Works for sms and mobile; WhatsApp is not supported here.\n\n- Numbers must be in international format 255XXXXXXXXX here (local formats like 0712... are rejected).\n- The Sender ID must be enabled for bulk (broadcast) sending on your account.\n- Duplicate protection: if the first message of a request is exactly the same as the first message of a request sent in the last 24 hours, the request is refused with \"Duplicate request sent within past 24 hour(s)\".", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Where to send: sms, mobile or whatsapp. See \"Channels\".", "schema": { "type": "string", "enum": [ "sms", "mobile", "whatsapp" ] }, "example": "sms" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "messages": [ { "to": "255712345678", "status": { "groupId": 18, "groupName": "PENDING", "id": 51, "name": "ENROUTE (SENT)", "description": "Message sent to next instance" }, "messageId": 7391827364512378881, "message": "Hi Asha, your balance is 5,000 TZS.", "smsCount": 1, "price": 20 }, { "to": "255754000111", "status": { "groupId": 18, "groupName": "PENDING", "id": 51, "name": "ENROUTE (SENT)", "description": "Message sent to next instance" }, "messageId": 7391827364512378882, "message": "Hi John, your balance is 12,500 TZS.", "smsCount": 1, "price": 20 } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "The list of messages, up to 500. Each item has \"from\", \"to\" (a number or a list of numbers in 255XXXXXXXXX format) and \"text\"." }, "reference": { "type": "string", "examples": [ "batch-77" ], "description": "Your own label for the whole batch (up to 50 characters)." }, "date": { "type": "string", "examples": [ "2026-12-01" ], "description": "Send later on this date, format YYYY-MM-DD (East Africa Time). Must be today or later. (Required with time.)" }, "time": { "type": "string", "examples": [ "08:30" ], "description": "Send later at this time, 24-hour format HH:MM (East Africa Time, UTC+3). (Required with date.)" } }, "required": [ "messages" ] }, "example": { "messages": [ { "from": "NEXTSMS", "to": "255712345678", "text": "Hi Asha, your balance is 5,000 TZS." }, { "from": "NEXTSMS", "to": "255754000111", "text": "Hi John, your balance is 12,500 TZS." } ], "reference": "batch-77" } } } } } }, "/link/{channel}/v2/text/single": { "get": { "operationId": "send_link_v2", "tags": [ "send" ], "summary": "Send with a simple link (GET)", "description": "Some older systems, devices and spreadsheets can only open a link. Put the token and message details in the address. It works like \"Send a message\", with the same fields as query parameters.\n\n- Links are often saved in browser history and server logs, which exposes your token. Use the POST endpoints whenever you can.\n- Not for WhatsApp.", "security": [ { "tokenQuery": [] } ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Where to send: sms, mobile or whatsapp. See \"Channels\".", "schema": { "type": "string", "enum": [ "sms", "mobile", "whatsapp" ] }, "example": "sms" }, { "name": "token", "in": "query", "required": true, "description": "Your API token. (v1 uses username and password parameters instead.)", "schema": { "type": "string", "examples": [ "YOUR_API_TOKEN" ] }, "example": "YOUR_API_TOKEN" }, { "name": "from", "in": "query", "required": false, "description": "Your approved Sender ID. (Required for sms.)", "schema": { "type": "string", "examples": [ "NEXTSMS" ] }, "example": "NEXTSMS" }, { "name": "to", "in": "query", "required": true, "description": "The phone number, 255XXXXXXXXX.", "schema": { "type": "string", "examples": [ "255712345678" ] }, "example": "255712345678" }, { "name": "text", "in": "query", "required": true, "description": "The message, URL-encoded (spaces become %20).", "schema": { "type": "string", "examples": [ "Hello from NextSMS" ] }, "example": "Hello from NextSMS" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "messages": [ { "to": "255712345678", "status": { "groupId": 18, "groupName": "PENDING", "id": 51, "name": "ENROUTE (SENT)", "description": "Message sent to next instance" }, "messageId": 7391827364512378881, "message": "Hello! Your order 1001 is ready for pickup.", "smsCount": 1, "price": 20 } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/{channel}/v2/test/text/single": { "post": { "operationId": "test_single_v2", "tags": [ "test" ], "summary": "Test a send (no message, no charge)", "description": "Exactly the same as \"Send a message\" (and the WhatsApp send), but nothing is sent, stored or charged. You get the same response, so you can check your Sender ID, numbers and message parts first. The messageId values in the answer are not real.\n\n- Your balance is not checked, so FAILED_NOT_ENOUGH_CREDITS never appears in a test.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Where to send: sms, mobile or whatsapp. See \"Channels\".", "schema": { "type": "string", "enum": [ "sms", "mobile", "whatsapp" ] }, "example": "sms" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "messages": [ { "to": "255712345678", "status": { "groupId": 18, "groupName": "PENDING", "id": 51, "name": "ENROUTE (SENT)", "description": "Message sent to next instance" }, "messageId": 7391827364512378881, "message": "Hello! Your order 1001 is ready for pickup.", "smsCount": 1, "price": 20 } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/{channel}/v2/test/text/multi": { "post": { "operationId": "test_multi_v2", "tags": [ "test" ], "summary": "Test a multi send (no message, no charge)", "description": "The same as \"Send different messages in one request\", but nothing is sent or charged.\n\n- Tests do not count for the 24-hour duplicate protection, so you can test the same request as often as you like and then send it for real. A test does warn you if the real request would be refused as a duplicate.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Where to send: sms, mobile or whatsapp. See \"Channels\".", "schema": { "type": "string", "enum": [ "sms", "mobile", "whatsapp" ] }, "example": "sms" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "messages": [ { "to": "255712345678", "status": { "groupId": 18, "groupName": "PENDING", "id": 51, "name": "ENROUTE (SENT)", "description": "Message sent to next instance" }, "messageId": 7391827364512378881, "message": "Hello! Your order 1001 is ready for pickup.", "smsCount": 1, "price": 20 } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "The same body as \"Send different messages in one request\"." } }, "required": [ "messages" ] }, "example": { "messages": [ { "from": "NEXTSMS", "to": "255712345678", "text": "Test for Asha" }, { "from": "NEXTSMS", "to": "255754000111", "text": "Test for John" } ] } } } } } }, "/api/{channel}/v2/sms_count": { "post": { "operationId": "sms_count_v2", "tags": [ "test" ], "summary": "Count SMS parts", "description": "Long messages are split into parts and each part is charged. A normal (GSM) SMS holds 160 characters, or 153 per part when longer. Emojis and non-English characters switch to Unicode: 70 characters, or 67 per part.\n\n- WhatsApp always counts as 1.\n- Texts longer than 15 GSM parts or 10 Unicode parts are rejected when sending.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Where to send: sms, mobile or whatsapp. See \"Channels\".", "schema": { "type": "string", "enum": [ "sms", "mobile", "whatsapp" ] }, "example": "sms" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "smsCount": 1, "charUsed": 11, "charRemaining": 149, "charPerSms": 160, "encoding": "GSM" } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "examples": [ "Hello World" ], "description": "The message to measure." } }, "required": [ "text" ] }, "example": { "text": "Hello World" } } } } } }, "/api/v2/reports": { "get": { "operationId": "reports_v2", "tags": [ "reports" ], "summary": "Get delivery reports", "description": "Returns delivery results (DELIVERED, UNDELIVERABLE, EXPIRED, …). Without messageId it works like an inbox: each call returns only reports you have not collected before, oldest first, and they are not returned again. Keep calling until \"results\" is empty. Prefer webhooks if your server can receive them.\n\n- Only messages that already have a delivery result appear here. To list everything you sent, including pending messages, use \"Get message logs\".", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "messageId", "in": "query", "required": false, "description": "Look up the report of one message. This can be repeated as often as you want.", "schema": { "type": "string", "examples": [ "7391827364512378881" ] }, "example": "7391827364512378881" }, { "name": "size", "in": "query", "required": false, "description": "How many reports to return, up to 200. Default 200.", "schema": { "type": "integer", "examples": [ 100 ] }, "example": 100 }, { "name": "sentSince", "in": "query", "required": false, "description": "Only messages sent on or after this date, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "sentUntil", "in": "query", "required": false, "description": "Only messages sent on or before this date, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "sender", "in": "query", "required": false, "description": "Only messages from this Sender ID.", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "required": false, "description": "Only messages sent with this reference.", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "Only this channel: sms, mobile or whatsapp.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "results": [ { "messageId": "7391827364512378881", "reference": "order-1001", "sentAt": "2026-10-20 10:15:00", "doneAt": "2026-10-20 10:15:07", "to": "255712345678", "channel": "Internet SMS", "from": "NEXTSMS", "smsCount": 1, "status": { "groupId": 20, "groupName": "DELIVERED", "id": 73, "name": "DELIVERED" }, "delivery": "DELIVERED" } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v2/logs": { "get": { "operationId": "logs_v2", "tags": [ "reports" ], "summary": "Get message logs", "description": "A searchable history of sent messages, newest first. Unlike reports, logs can be fetched again and again. Use limit and offset to page through.\n\n- Searching logs by messageId is not allowed. Use \"Get delivery reports\" with messageId instead.\n- The message text is included only when limit is 15 or less. Use \"Get message logs with text\" for that.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sentSince", "in": "query", "required": false, "description": "Only messages sent on or after this date, YYYY-MM-DD.", "schema": { "type": "string", "examples": [ "2026-10-01" ] }, "example": "2026-10-01" }, { "name": "sentUntil", "in": "query", "required": false, "description": "Only messages sent on or before this date, YYYY-MM-DD.", "schema": { "type": "string", "examples": [ "2026-10-20" ] }, "example": "2026-10-20" }, { "name": "from", "in": "query", "required": false, "description": "Only messages from this Sender ID.", "schema": { "type": "string", "examples": [ "NEXTSMS" ] }, "example": "NEXTSMS" }, { "name": "to", "in": "query", "required": false, "description": "Only messages to this phone number (255XXXXXXXXX).", "schema": { "type": "string", "examples": [ "255712345678" ] }, "example": "255712345678" }, { "name": "reference", "in": "query", "required": false, "description": "Only messages sent with this reference.", "schema": { "type": "string", "examples": [ "order-1001" ] }, "example": "order-1001" }, { "name": "channel", "in": "query", "required": false, "description": "Only this channel: sms, mobile or whatsapp.", "schema": { "type": "string", "examples": [ "sms" ] }, "example": "sms" }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many rows (for paging).", "schema": { "type": "integer", "examples": [ 0 ] }, "example": 0 }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return, up to 200. Default 200.", "schema": { "type": "integer", "examples": [ 50 ] }, "example": 50 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "results": [ { "messageId": "7391827364512378881", "reference": "order-1001", "sentAt": "2026-10-20 10:15:00", "doneAt": "2026-10-20 10:15:07", "to": "255712345678", "channel": "Internet SMS", "from": "NEXTSMS", "smsCount": 1, "status": { "groupId": 20, "groupName": "DELIVERED", "id": 73, "name": "DELIVERED" }, "delivery": "DELIVERED" } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v2/msglogs": { "get": { "operationId": "msglogs_v2", "tags": [ "reports" ], "summary": "Get message logs with text", "description": "Returns 15 rows at a time by default, each with the \"text\" that was sent.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sentSince", "in": "query", "required": false, "description": "Only messages sent on or after this date, YYYY-MM-DD.", "schema": { "type": "string", "examples": [ "2026-10-01" ] }, "example": "2026-10-01" }, { "name": "sentUntil", "in": "query", "required": false, "description": "Only messages sent on or before this date, YYYY-MM-DD.", "schema": { "type": "string", "examples": [ "2026-10-20" ] }, "example": "2026-10-20" }, { "name": "from", "in": "query", "required": false, "description": "Only messages from this Sender ID.", "schema": { "type": "string", "examples": [ "NEXTSMS" ] }, "example": "NEXTSMS" }, { "name": "to", "in": "query", "required": false, "description": "Only messages to this phone number (255XXXXXXXXX).", "schema": { "type": "string", "examples": [ "255712345678" ] }, "example": "255712345678" }, { "name": "reference", "in": "query", "required": false, "description": "Only messages sent with this reference.", "schema": { "type": "string", "examples": [ "order-1001" ] }, "example": "order-1001" }, { "name": "channel", "in": "query", "required": false, "description": "Only this channel: sms, mobile or whatsapp.", "schema": { "type": "string", "examples": [ "sms" ] }, "example": "sms" }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many rows (for paging).", "schema": { "type": "integer", "examples": [ 0 ] }, "example": 0 }, { "name": "limit", "in": "query", "required": false, "description": "How many rows to return. Default 15. Above 15 the text is left out.", "schema": { "type": "integer", "examples": [ 15 ] }, "example": 15 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "results": [ { "messageId": "7391827364512378881", "reference": "order-1001", "sentAt": "2026-10-20 10:15:00", "doneAt": "2026-10-20 10:15:07", "to": "255712345678", "channel": "Internet SMS", "from": "NEXTSMS", "smsCount": 1, "status": { "groupId": 20, "groupName": "DELIVERED", "id": 73, "name": "DELIVERED" }, "delivery": "DELIVERED", "text": "Hello! Your order 1001 is ready for pickup." } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token from the dashboard: Customer Profile (top-right menu) → Customization → API Keys." }, "tokenQuery": { "type": "apiKey", "in": "query", "name": "token", "description": "API token as a query parameter (GET link endpoint only)." } }, "responses": { "401": { "description": "Your token is wrong, or the account is not active. Copy the token again from Customer Profile (top-right menu) → Customization → API Keys and send it as \"Authorization: Bearer \".", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "integer" }, "message": { "type": "string" }, "errors": { "type": "object" } } }, "example": { "success": false, "status": 401, "message": "Not Authorized, Customer Error", "errors": { "Authenticate": "Token" } } } } }, "422": { "description": "A field is missing or has the wrong format. Read \"errors\": it lists every field that needs fixing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "integer" }, "message": { "type": "string" }, "errors": { "type": "object" } } }, "example": { "message": "The from field is required. (and 1 more error)", "errors": { "from": [ "The from field is required." ], "text": [ "The text field is required." ] } } } } }, "429": { "description": "Too many failed sign-in attempts: 5 wrong passwords for one username, or 30 failed sign-ins of any kind, from your IP address within 15 minutes. Wait for the time in the Retry-After header (seconds), then try again with the correct token. Successful requests are never limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "integer" }, "message": { "type": "string" }, "errors": { "type": "object" } } }, "example": { "success": false, "status": 429, "message": "Too many failed sign-in attempts. Try again in 15 minute(s).", "errors": { "Authenticate": "Token" } } } } }, "500": { "description": "Something went wrong on our side, or the request could not be read. Check that your JSON is valid, then try again. If it continues, contact support with the time of the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "integer" }, "message": { "type": "string" }, "errors": { "type": "object" } } }, "example": { "success": false, "status": 500, "message": "Error processing send request, contact support!!" } } } } } } }