# Kudosity Documentation ## Guides - [Claude Code Plugin](https://developers.kudosity.com/docs/claude-plugin.md) - [GitHub Copilot Extension](https://developers.kudosity.com/docs/copilot-extension.md) - [Gemini CLI Extension](https://developers.kudosity.com/docs/gemini-extension.md) - [Kudosity MCP Server](https://developers.kudosity.com/docs/mcp.md) - [OpenClaw Plugin](https://developers.kudosity.com/docs/openclaw-plugin.md) - [Overview](https://developers.kudosity.com/docs/overview.md) - [Send messages from AI agents & workflows](https://developers.kudosity.com/docs/send-messages-from-ai-agents.md) - [SMS GitHub Action](https://developers.kudosity.com/docs/sms-action.md) - [Getting Started with Kudosity in Two Minutes 🕑](https://developers.kudosity.com/docs/getting-started.md): This page will help you get started with Kudosity. You'll be up and running in a jiffy! - [Step 1: Create a Kudosity Account](https://developers.kudosity.com/docs/step-1-create-a-kudosity-account.md) - [Step 2: Get Your API Key and Secret](https://developers.kudosity.com/docs/step-2-get-your-api-key.md) - [Step 3: Send an SMS](https://developers.kudosity.com/docs/step-3-make-an-api-request.md) - [Validating Webhook Signatures from Kudosity](https://developers.kudosity.com/docs/validating-webhook-signatures-from-kudosity.md) - [RBM Agents](https://developers.kudosity.com/docs/rbm-agents.md) - [RCS Beta Opportunity](https://developers.kudosity.com/docs/rcs-beta.md) - [Introduction to RCS](https://developers.kudosity.com/docs/rcs-introduction.md) - [RCS Agent Registration Process](https://developers.kudosity.com/docs/rcs-onboarding.md) - [Connect Salesforce to Your Kudosity Account](https://developers.kudosity.com/docs/connect-salesforce-to-your-kudosity-account.md) - [Installation Guide](https://developers.kudosity.com/docs/getting-started-to-salesforce-integration.md) - [Install the Package](https://developers.kudosity.com/docs/install-the-package.md) - [Set Default Country and Sender ID](https://developers.kudosity.com/docs/set-default-country-and-sender-id.md) - [Set Up Live Responses / Reporting (ECA Setup)](https://developers.kudosity.com/docs/set-up-live-responses-reporting-eca-setup.md): This step enables live delivery reporting, inbound replies, and link hit notifications back into Salesforce. This uses Salesforce's External Client App (ECA) framework. - [User-Level Sender ID and Country (Admin Feature)](https://developers.kudosity.com/docs/user-level-sender-id-and-country-admin-feature.md) - [Advanced Campaign Setup](https://developers.kudosity.com/docs/advanced-campaign-setup.md) - [Campaign Setup](https://developers.kudosity.com/docs/campaign-setup.md) - [User Guide](https://developers.kudosity.com/docs/user-guide.md) - [Received Messages & Link Hits](https://developers.kudosity.com/docs/received-messages-link-hits.md) - [Recipient Contacts](https://developers.kudosity.com/docs/recipient-contacts.md) - [Schedule & Send](https://developers.kudosity.com/docs/schedule-send.md) - [Sent Messages](https://developers.kudosity.com/docs/sent-messages.md) - [Universal Messaging App](https://developers.kudosity.com/docs/universal-messaging-app.md) - [Introduction to WhatsApp](https://developers.kudosity.com/docs/introduction-to-whatsapp.md) - [WhatsApp Content Types](https://developers.kudosity.com/docs/whatsapp-content-types.md) - [WhatsApp Business API Onboarding Guide](https://developers.kudosity.com/docs/whatsapp-registration-process.md) - [Register your WhatsApp Sender](https://developers.kudosity.com/docs/register-your-whatsapp-sender.md) - [Understanding WhatsApp Sender Registration](https://developers.kudosity.com/docs/understanding-whatsapp-sender-registration.md) - [Verify your Meta Business Portfolio](https://developers.kudosity.com/docs/verify-your-whatsapp-business-account.md) - [WhatsApp Template Guide](https://developers.kudosity.com/docs/whatsapp-template-guide.md) - [WhatsApp Verified Senders](https://developers.kudosity.com/docs/whatsapp-verified-senders.md) ## API Reference - [Which API Should I Use?](https://developers.kudosity.com/reference/about-our-apis.md) - [Authentication](https://developers.kudosity.com/reference/authentication.md) - [Error Registry](https://developers.kudosity.com/reference/errors.md) - [Pagination](https://developers.kudosity.com/reference/pagination.md) - [Postman](https://developers.kudosity.com/reference/postman.md) - [Rate Limiting](https://developers.kudosity.com/reference/rate-limiting.md) - [Using JSON and XML](https://developers.kudosity.com/reference/requests.md) - [Status Codes](https://developers.kudosity.com/reference/status-codes.md) - [Timestamps](https://developers.kudosity.com/reference/timestamps.md) - [Webhooks](https://developers.kudosity.com/reference/webhooks-1.md) - [About MMS](https://developers.kudosity.com/reference/about-mms.md) - [Get MMS](https://developers.kudosity.com/reference/get_v2-mms-id.md): This request retrieves the information of an existing sent MMS message. You only need to supply the unique message id that was returned upon creation. - [Send MMS](https://developers.kudosity.com/reference/post_v2-mms.md): The Send MMS endpoint allows you to send multimedia messages (MMS) to recipients. - [Get RCS message](https://developers.kudosity.com/reference/get_v2-rcs-messages-id.md): Retrieves details of a previously sent RCS message by its unique identifier. Returns message content, delivery status, and metadata. - [List RCS messages](https://developers.kudosity.com/reference/get_v2-rcs-messages.md): Retrieves a list of RCS messages for your account with flexible date filtering. Messages are returned in reverse chronological order (newest first). **Date Filtering:** - Preset ranges (last_week, last_thirty, last_month): Calculated using your account timezone - Custom date ranges: Use RFC3339 timestamps (max 90 days) - The 'all' option provides up to 365 days of history - All timestamps in responses are returned in UTC format **Pagination:** - Cursor-based pagination for efficient data retrieval - Control page size with the limit parameter (1-100 messages per page) - [Check RCS capability for phone numbers](https://developers.kudosity.com/reference/post_v2-rcs-capabilities.md): Synchronously checks whether a list of phone numbers can receive RCS from your sender. Use this **before** sending to decide between RCS and SMS fallback. Designed for routing-time lookups: small batches (1–10 numbers recommended for best latency), immediate response. Results are best-effort and reflect capability at the moment of the lookup. **Do not use this as a hard gate** on sending — treat `UNKNOWN` as reachable and rely on SMS fallback for hard delivery guarantees. - [Send RCS message](https://developers.kudosity.com/reference/post_v2-rcs-messages.md): This endpoint is in beta and may change in future versions. Sends an RCS message to a single recipient. - [Delete a sender by phone number](https://developers.kudosity.com/reference/delete_v2-senders-phone-numbers-phone-number.md): Deletes a sender phone number from the account. - If the account does not use parent/child accounts, the API ignores `child_account_id` and deletes the sender from the authenticated account. - If the account is a parent account and you omit `child_account_id`, the API deletes the sender from the parent account. - If you provide `child_account_id`, the API deletes the sender from that child account. - [List sender registrations](https://developers.kudosity.com/reference/get_v2-senders-registrations.md): Returns a paginated list of sender registrations for the authenticated account. - If the account does not use parent/child accounts, the API returns registrations for the authenticated account. - If the account is a parent account, the API returns registrations for the parent account and all child accounts. - [Confirm a verification code](https://developers.kudosity.com/reference/post_v2-senders-registrations-registration-id-verifications-confirmation.md): Confirms a sender registration by submitting the verification code. On success, the verification `status` becomes `CONFIRMED` and the sender registration `status` becomes `VERIFIED`. If you exceed the allowed attempts, the verification becomes `FAILED`. Request a new verification code to try again. - [Request a verification code](https://developers.kudosity.com/reference/post_v2-senders-registrations-registration-id-verifications.md): Requests a verification code for a sender registration. This endpoint supports registrations with `type` = `PERSONAL_MOBILE_NUMBER` only. - The API delivers the code to the registered sender number using the selected `method`, such as `SMS`. - Codes expire after 30 minutes. - You have a maximum of 5 attempts to confirm the code. - [Create a sender registration](https://developers.kudosity.com/reference/post_v2-senders-registrations.md): Creates a sender registration and sets `status` to `PENDING_APPROVAL`. - If the account does not use parent/child accounts, the API ignores `child_account_id` and registers the sender for the authenticated account. - If the account is a parent account and you omit `child_account_id`, the API registers the sender for the parent account. - If you provide `child_account_id`, the API registers the sender for that child account. - If a registration for the same sender was already created within the last 30 minutes (for the same account or child account), the API returns `429 Too Many Requests`. This prevents abuse of the verification retry limit. - Any existing `PENDING_APPROVAL` registration for the same sender (for the same account or child account) is automatically cancelled before the new one is created. - [Get SMS](https://developers.kudosity.com/reference/get_v2-sms-id.md): Retrieves information about an existing SMS message. You only need to supply the unique message id that was returned upon message creation. - [List SMS](https://developers.kudosity.com/reference/get_v2-sms.md): Retrieves a list of SMS messages. You can limit the number of messages returned and filter by properties listed in the parameters section. - [Send SMS](https://developers.kudosity.com/reference/post_v2-sms.md): Send a message from sender to recipient using the values shown in the parameters section. - [About Webhooks](https://developers.kudosity.com/reference/about-webhooks.md) - [Delete Webhook](https://developers.kudosity.com/reference/delete_v2-webhook-id.md) - [Get a webhook by ID](https://developers.kudosity.com/reference/get_v2-webhook-id.md) - [Retrieve all webhooks](https://developers.kudosity.com/reference/get_v2-webhook.md) - [Create Webhook](https://developers.kudosity.com/reference/post_v2-webhook.md): We use webhooks to let your application know when events happen, such as receiving an SMS message. When the event occurs, the system makes an HTTP request (usually a POST) to the URL you configured for the webhook. The request will include details of the event such as the incoming phone number or the body of an incoming message. - [Update Webhook](https://developers.kudosity.com/reference/put_v2-webhook-id.md): Updates the webhook. Any fields not provided in the request body will reset to their default values. - [Get WhatsApp message](https://developers.kudosity.com/reference/get_v2-whatsapp-messages-id.md): Retrieves details of a previously sent WhatsApp message by its unique identifier. Returns message content, delivery status, and metadata. - [List WhatsApp messages](https://developers.kudosity.com/reference/get_v2-whatsapp-messages.md): Retrieves a list of WhatsApp messages for your account with flexible date filtering. Messages are returned in reverse chronological order (newest first). **Date Filtering:** - Preset ranges (last_week, last_thirty, last_month): Calculated using your account timezone - Custom date ranges: Use RFC3339 timestamps (max 90 days) - The 'all' option provides up to 365 days of history - All timestamps in responses are returned in UTC format **Pagination:** - Cursor-based pagination for efficient data retrieval - Control page size with the limit parameter (1-100 messages per page) - [Send WhatsApp message](https://developers.kudosity.com/reference/post_v2-whatsapp-messages.md): Sends a single templated message to a single recipient. Templates need to be registered and pre-approved by WhatsApp. - [Get Balance](https://developers.kudosity.com/reference/get_get-balance-json.md): Account information. - [Bulk Add Contacts from CSV File](https://developers.kudosity.com/reference/post_add-contacts-bulk-json.md): Add bulk contacts to a list from a file The add-contacts-bulk request can be used to add a CSV file of contacts to an existing list. It can also be used to create a new list and upload a CSV file of contacts to it. If a contact is added that already exists in a list, any existing data will be updated. **The return code 200 is only used to indicate that the API call has successfully hit our server. It in no way indicates if the contacts have been added\updated successfully. To find the status of an upload, including error messages, you must use the add-contacts-bulk-progress endpoint.** ``` CSV File Format and Example: Firstname,Lastname,Mobile,"Custom Field 1" Jane,Doe,61412345678,10.44 The minimum required for successful import is Mobile. The order above must be followed. ``` - [Check Progress Of Import](https://developers.kudosity.com/reference/post_add-contacts-bulk-progress-json.md): For large lists in excess of 50,000 contacts, it can take some time to process. This request will let you see the progress of the import. - [Add Field to List](https://developers.kudosity.com/reference/post_add-field-to-list-json.md): Add or update custom fields on an existing list - [Add List](https://developers.kudosity.com/reference/post_add-list-json.md): Create New Contact List - [Add Contact to List](https://developers.kudosity.com/reference/post_add-to-list-json.md): Adds a new contact to a list If a contact is added that already exists it will be ignored, not updated. - [Remove Contact](https://developers.kudosity.com/reference/post_delete-from-list-json.md): Delete contact from one or all lists - [Update Contact](https://developers.kudosity.com/reference/post_edit-list-member-json.md): Edit a contact that exists on a list Used for adding new or updated custom data to a contact on a list. - [Opt Out/Unsubscribe Contact](https://developers.kudosity.com/reference/post_optout-list-member-json.md): Opt Out List Member Unsubscribe contact from one or all lists If sending marketing by law you must enable an unsubscribe method. [Anti-Spam Policy](https://help.kudosity.com/s/article/44001077041-anti-spam-policy) - [Remove List](https://developers.kudosity.com/reference/post_remove-list-json.md): Delete a list and its contacts - [Add Email](https://developers.kudosity.com/reference/post_add-email-json.md): Authorise Email Address - [Delete Email](https://developers.kudosity.com/reference/post_delete-email-json.md): Remove an email address from the Email to SMS authorised list. - [Add Keyword](https://developers.kudosity.com/reference/post_add-keyword-json.md): Add New Keyword - [Edit Keyword](https://developers.kudosity.com/reference/post_edit-keyword-json.md): Edit an existing keyword. - [Get Keywords](https://developers.kudosity.com/reference/post_get-keywords-json.md): Get a list of existing keywords. - [Get Numbers](https://developers.kudosity.com/reference/get_get-numbers-json.md): Edit inbound options for a dedicated virtual number. **Get a list of numbers leased by you or available to be leased.** Dedicated virtual numbers are used to receive MO (Mobile Originated) messages. They also make sure that all of your messages are sent from a number that is always the same. Dedicated Virtual Number availability is limited to certain countries. Check [Global SMS delivery list](https://support.transmitsms.com/support/solutions/articles/44001940675-global-sms-delivery-list) for availability for your destination country. ## Pagination This endpoint supports pagination using the page/max pattern: **Parameters:** - `page`: Page number starting from 1 (default: 1) - `max`: Maximum results per page (default: varies, recommended: 10-100) - `filter`: Choose 'owned' or 'available' (default: owned) **Response Structure:** The response includes pagination metadata: - `page.count`: Total number of pages available - `page.number`: Current page number - `numbers_total`: Total count of numbers matching the filter **Navigation Examples:** ``` # First page of owned numbers (default) GET /get-numbers.json # Second page with 20 results per page GET /get-numbers.json?page=2&max=20 # Available numbers for leasing GET /get-numbers.json?filter=available&max=50 # Navigate through all pages GET /get-numbers.json?page=1&max=100 GET /get-numbers.json?page=2&max=100 # Continue until page.number >= page.count ``` **Best Practices:** - Use max=10-20 for UI display purposes - Use max=50-100 for administrative tasks - Check page.count to determine if more pages exist - Filter by 'owned' vs 'available' to reduce dataset size - For large accounts, consider filtering by country or status - [Edit Number Options](https://developers.kudosity.com/reference/post_edit-number-options-json.md): Edit inbound options for a dedicated virtual number. These options adjust behaviour for messages that are sent to this number. - [Get Number Information](https://developers.kudosity.com/reference/post_get-number-json.md): Get detailed information about a number you have leased. - [Add Dedicated Virtual Number](https://developers.kudosity.com/reference/post_lease-number-json.md): Lease Number Dedicated virtual numbers are used to receive MO (Mobile Originated) messages. They also make sure that all of your messages are sent from a number that is always the same. Dedicated Virtual Number availability is limited to certain countries. Check [Global Sender ID Information](https://portal.transmitsms.com/s/article/Global-Sender-ID-Information) for availability for your destination coutry. - [Get SMS Sent to Account](https://developers.kudosity.com/reference/get_get-contact-sms-stats-json.md): This will return paginated information regarding individual messages sent to provided mobile number. - [Get Information About All Lists](https://developers.kudosity.com/reference/get_get-lists-json.md): Get information about all lists in your account This will return metadata on all your lists ## Pagination This endpoint supports pagination using the page/max pattern: **Parameters:** - `page`: Page number starting from 1 (default: 1) - `max`: Maximum results per page (default: varies, recommended: 10-50) **Response Structure:** The response includes pagination metadata: - `page.count`: Total number of pages available - `page.number`: Current page number - `lists_total`: Total count of lists in your account **Navigation Examples:** ``` # First page of lists (default) GET /get-lists.json # Second page with 20 results per page GET /get-lists.json?page=2&max=20 # Get all lists with larger page size GET /get-lists.json?max=50 # Navigate through all pages GET /get-lists.json?page=1&max=25 GET /get-lists.json?page=2&max=25 # Continue until page.number >= page.count ``` **Best Practices:** - Use max=10-25 for UI display purposes - Use max=50 for administrative tasks or bulk operations - Check page.count to determine if more pages exist - For accounts with many lists, use appropriate page sizes to balance performance and usability - Consider filtering or searching if you need specific lists rather than paginating through all - [Get Contact Information](https://developers.kudosity.com/reference/post_get-contact-json.md): Get information about a contact on a list - [Get Information About A List](https://developers.kudosity.com/reference/post_get-list-json.md): Get detailed information about a list, return custom fields and its contacts. This will return paginated information regarding individual contacts on a list and their data. - [Get Message Report](https://developers.kudosity.com/reference/post_get-message-report-json.md): Retrieve information on messages sent during a period of time It will also return all custom data fields associated to contacts in the list - [Get SMS Delivery Status](https://developers.kudosity.com/reference/post_get-sms-delivery-status-json.md): Retrieves detailed information about messages sent to a specific recipient. This included full message content including populated variables. - [Get Message/Campaign Information](https://developers.kudosity.com/reference/post_get-sms-json.md): This will return information about the campaign, including the message, list etc. It will not however return individual messages with populated variables or tracking links. To retrieve final individual messages use **get-sms-delivery-status.** - [Get SMS Sent Count](https://developers.kudosity.com/reference/post_get-sms-sent-count-json.md): Retrieves total number of SMS sent in a given timeframe - [Get Message/Campaign Recipients](https://developers.kudosity.com/reference/post_get-sms-sent-json.md): Get information about a message send and it's recipients This will return paginated information regarding individual recipients on a campaign or message send. - [Get Message/Campaign Report](https://developers.kudosity.com/reference/post_get-sms-stats-json.md): Get the delivery status of a message or campaign that you have sent. Count of different reporting stats we collect. Delivery reports are marked using a DLR (Delivery Receipt) or Acknowledgement (ACK) returned from the carrier, a DLR is a handset level report and an ACK is simply a response from the carrier that the request was received. Global carriers have different functionality available. See our Global Delivery List for details. - [Get Activity Report](https://developers.kudosity.com/reference/post_get-user-sms-sent-json.md): Retrieve information on messages sent during a period of time - [Get Responses by Time Frame](https://developers.kudosity.com/reference/get_get-user-sms-responses-json.md): Gets the messsages from a defined timeframe. ## Pagination This endpoint supports pagination using the page/max pattern: **Parameters:** - `page`: Page number starting from 1 (default: 1) - `max`: Maximum results per page (default: 10, recommended: 10-100) - `mobile`: Required mobile number filter (E.164 format) - `start`/`end`: Optional date range filters **Response Structure:** The response includes pagination metadata: - `page.count`: Total number of pages available - `page.number`: Current page number - `total`: Total count of SMS responses matching the filters **Navigation Examples:** ``` # First page of responses for a mobile number (default) GET /get-user-sms-responses.json?mobile=61478038915 # Second page with 25 results per page GET /get-user-sms-responses.json?mobile=61478038915&page=2&max=25 # Responses within date range with pagination GET /get-user-sms-responses.json?mobile=61478038915&start=2020-04-01T00:00:00Z&end=2020-04-30T23:59:59Z&max=50 # Navigate through all pages GET /get-user-sms-responses.json?mobile=61478038915&page=1&max=20 GET /get-user-sms-responses.json?mobile=61478038915&page=2&max=20 # Continue until page.number >= page.count ``` **Best Practices:** - Use max=10-25 for UI display of conversation history - Use max=50-100 for data export or analysis tasks - Always specify date ranges for large datasets to improve performance - Check page.count to determine if more pages exist - Use sorting parameters (sort_field, order) to organize results effectively - Consider the mobile number is required - this endpoint is designed for per-contact message history - [Cancel SMS](https://developers.kudosity.com/reference/post_cancel-sms-json.md): Messages scheduled can be cancelled using the message ID. Return a JSON or XML response by adding the appropriate extension to the base url (See examples). - [Format Number](https://developers.kudosity.com/reference/post_format-number-json.md): In the majority of cases, mobile phone number data coming from external systems is not ideal for SMS delivery. For highest reliability and to be able to route correctly a mobile number should be formatted in international format E.164 Normally however a number is stored in a CRM or contact database in local format, with spaces, hyphens and other types of unwanted characters that can cause a delivery to fail. The format-number call is used to sanitise a number by combining the country and the number. eg. > Australia 0438 333 061 will become 61438333061 > New Zealand 0212172782 will become 64212172782 > USA (281) 869-1226 will become 12818691226 - [Get Responses by MessageID, Keyword or Mobile](https://developers.kudosity.com/reference/post_get-sms-responses-json.md): Responses to your outgoing messages can be picked up in a few different ways. Your DLR Callback URL in your account settings, is the default URL we post incoming DLR's to. You can also set the DLR Callback URL separately for individual messages, using a parameter on the send-sms call. You can also poll the following endpoints for responses. - [Send SMS](https://developers.kudosity.com/reference/post_send-sms-json.md): You can elect to pass us the recipient numbers from your database each time you make a call, or you can elect to store recipient data in a contact list and submit only the list_id to trigger the send. This is best for large databases. To add a list please refer to the add-list call. ## Changelog - [Send messages from AI agents & workflows](https://developers.kudosity.com/changelog/send-messages-from-ai-agents-workflows.md) - [Kudosity for GitHub: Copilot Extension and SMS Action](https://developers.kudosity.com/changelog/kudosity-for-github-copilot-extension-and-sms-action.md) - [🤖 OpenClaw Plugin for AI Developers](https://developers.kudosity.com/changelog/openclaw-plugin-for-ai-developers.md) - [Gemini CLI Extension for AI Developers](https://developers.kudosity.com/changelog/gemini-cli-extension-for-ai-developers.md) - [Claude Plugin for AI Developers](https://developers.kudosity.com/changelog/claude-plugin-for-ai-developers.md)