openapi: 3.2.0 info: title: Transmit Message Whats App API description: Transmit APIs version: '20250101' x-go-package: github.com/oapi-codegen/runtime servers: - url: https://api.transmitmessage.com security: - ApiKeyAuth: [] tags: - name: WhatsApp paths: /v2/whatsapp/messages: get: tags: - WhatsApp summary: List WhatsApp messages description: '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) ' security: - ApiKeyAuth: [] parameters: - name: date_range in: query description: 'Predefined date range filter. Preset ranges use your account timezone to calculate relative dates: - ''last_week'': Last 7 days from midnight in your account timezone - ''last_thirty'': Last 30 days from midnight in your account timezone - ''last_month'': Previous calendar month in your account timezone - ''all'': All dates (limited to last 365 days) - default - ''custom_date'': Use start_date and end_date parameters with explicit RFC3339 timestamps ' schema: type: string enum: - last_week - last_thirty - last_month - all - custom_date default: all x-go-type-skip-optional-pointer: true example: all - name: start_date in: query description: 'Start date for custom date range in RFC3339 format (e.g., 2025-08-26T10:30:00Z). Required when date_range is ''custom_date''. Must be before end_date. ' schema: type: string x-go-type-skip-optional-pointer: true example: '2025-12-01T00:00:00Z' - name: end_date in: query description: 'End date for custom date range in RFC3339 format (e.g., 2025-08-26T23:59:59Z). Required when date_range is ''custom_date''. Must be after start_date. The range between start_date and end_date cannot exceed 90 days. ' schema: type: string x-go-type-skip-optional-pointer: true example: '2025-12-31T23:59:59Z' - name: limit in: query required: false description: Maximum number of messages to return per page (1-100, default 25). schema: type: integer format: int32 minimum: 1 maximum: 100 default: 25 x-go-type-skip-optional-pointer: true example: 25 - name: cursor in: query required: false description: 'Pagination cursor returned from a previous request. Pass the next_cursor or prev_cursor value from a previous response to fetch the next or previous page of results. Omit for the first page. ' schema: type: string x-go-type-skip-optional-pointer: true example: MTIzNDU2 - name: direction in: query description: 'Pagination direction when using a cursor: - ''next'': Get older messages (default, moves forward through history) - ''prev'': Get newer messages (moves backward through history) ' schema: type: string enum: - next - prev default: next x-go-type-skip-optional-pointer: true example: next - name: campaign_id in: query required: false description: 'Restrict results to messages belonging to a single campaign (UUID). Omit to return messages across all campaigns. ' schema: type: string format: uuid x-go-type: string x-go-type-skip-optional-pointer: true example: 9b2e4c1a-7f3d-4a8b-9c5e-2d1f6a8b3c4d responses: '200': $ref: '#/components/responses/ListWhatsappMessagesSuccessResponse' '400': $ref: '#/components/responses/InputValidationResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' post: tags: - WhatsApp summary: Send WhatsApp message description: Sends a single templated message to a single recipient. Templates need to be registered and pre-approved by WhatsApp. security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappRequest' responses: '200': $ref: '#/components/responses/SuccessResponse' '400': $ref: '#/components/responses/InputValidationResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' /v2/whatsapp/messages/{id}: get: tags: - WhatsApp summary: Get WhatsApp message description: 'Retrieves details of a previously sent WhatsApp message by its unique identifier. Returns message content, delivery status, and metadata. ' security: - ApiKeyAuth: [] parameters: - name: id in: path required: true description: Unique identifier of the WhatsApp message to retrieve schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 responses: '200': $ref: '#/components/responses/GetWhatsappSuccessResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '404': $ref: '#/components/responses/NotFoundErrorResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: schemas: Text: type: object description: Text content for the message. properties: message: type: string minLength: 1 description: The text message body. required: - message CustomContent: type: object properties: custom: $ref: '#/components/schemas/Custom' required: - custom CommonErrorResponse: allOf: - type: object properties: error: $ref: '#/components/schemas/ProblemDetails' required: - error - $ref: '#/components/schemas/CommonResponseMeta' SMSFallback: type: object description: SMS fallback message details. properties: sender: type: string description: The sender number to use for SMS fallback, which can be in [E.164](http://en.wikipedia.org/wiki/E.164) international format or an alphanumeric sender ID. x-go-type-skip-optional-pointer: true message: type: string description: The message to send via SMS. required: - message WhatsappRequest: type: object properties: sender: type: string x-go-type-skip-optional-pointer: true description: 'Registered WhatsApp sender number. - Must be in **international format** following the [E.164 standard](http://en.wikipedia.org/wiki/E.164) (e.g., +14155238886). - Number must be registered with the WhatsApp Business API. - **Optional.** When omitted, the account''s sender is used automatically. Accounts with multiple senders must specify one. ' recipient: type: string format: phone description: 'Recipient phone number in international format. - Must follow **E.164 format** (e.g., `+14155238886` for a US number). - No spaces, dashes, or special characters. - The recipient must **have an active WhatsApp account**. - Ensure the recipient **has opted in** to receive WhatsApp messages. ' content_type: $ref: '#/components/schemas/WhatsappContentType' content: type: object description: "The message content to be sent.\n\n- Must follow the WhastApp-approved **template format** or be a **custom object** following the Meta Cloud API guidelines.\n- **Example JSON (Text Content):**\n ```json\n {\n \"text\": {\n \"message\": \"hello, world!\",\n }\n }\n ```\n- **Example JSON (Template Content):**\n ```json\n {\n \"template\": {\n \"name\": \"order_update\",\n \"parameters\": [\"123456\"]\n }\n }\n ```\n- **Example JSON (Custom Content):**\n ```json\n {\n \"custom\": {\n \"type\": \"template\",\n \"template\": {\n \"name\": \"template_img_simple_1\",\n \"language\": {\n \"code\": \"en\",\n \"policy\": \"deterministic\"\n },\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"parameters\": [\n {\n \"type\": \"image\",\n \"image\": {\n \"link\": \"https://image-test.jpg\"\n }\n }\n ]\n }\n ]\n }\n }\n }\n ```\n" oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/TemplateContent' - $ref: '#/components/schemas/CustomContent' sms_fallback: $ref: '#/components/schemas/SMSFallback' message_ref: type: string x-go-type-skip-optional-pointer: true description: "A unique reference ID supplied by your system to track messages.\n\n- **Maximum Length:** 500 characters.\n- This `message_ref` will be included in webhook events, allowing you to correlate sent messages with received events.\n\n**Example Usage:**\n - Sending a message with `message_ref: \"order-12345\"`\n - Receiving a delivery webhook containing `message_ref: \"order-12345\"`, confirming it was delivered.\n" required: - recipient - content_type - content example: sender: '14155238886' recipient: '61411122211' content_type: template content: template: name: welcome_new_customer parameters: - Joe message_ref: optional-ref-123 ProblemDetails: description: 'A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. ' type: object properties: type: $ref: '#/components/schemas/Uri' title: type: string description: A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). detail: type: string description: A human-readable explanation specific to this occurrence of the problem status: type: integer description: The HTTP status code corresponding to this error. required: - type - title - detail - status example: type: https://developers.kudosity.com/reference/errors title: Description of the type of problem that occurred detail: Description of specific occurrence of the problem status: 400 WhatsappMessageEvent: type: object description: Lifecycle event for a WhatsApp message. properties: event_type: type: string description: Type of event that occurred. enum: - SENT - DELIVERED - READ - FAILED created_at: type: string format: date-time description: Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the event occurred. details: type: string description: Description of the event. required: - event_type - created_at - details example: event_type: DELIVERED created_at: '2024-01-15T14:31:42Z' details: Message delivered to recipient device TextContent: type: object properties: text: $ref: '#/components/schemas/Text' required: - text Uri: type: string description: string providing an URI formatted according to IETF RFC 3986. format: uri Template: type: object description: Template details for the message content. properties: name: type: string description: 'The **exact name** of the WhatsApp template. - **Format:** Lowercase, alphanumeric, underscores only. - **Example:** `order_confirmation` - **Must be pre-approved** in your WhatsApp Business account. ' parameters: type: array description: "The **dynamic values** to populate placeholdes in the template message.\n\n- The number of parameters **must match** the template placeholders.\n- Supports **text only** (strings). Other types (e.g., images, documents) are not allowed.\n- **Example Usage:**\n - Template: `\"Hello, {1}! Your order {2} has been shipped.\"`\n - Parameters: `[\"Tony\", \"#12345\"]`\n - Final message: `\"Hello, Tony! Your order #12345 has been shipped.\"`\n" items: type: string locale: type: string x-go-type-skip-optional-pointer: true description: Optional locale for the template (e.g., en_US), if not provided, the default locale is `en`. required: - name WhatsappContentType: type: string description: Type of the message content. enum: - text - template - custom WhatsappResponse: type: object properties: id: type: string description: Unique identifier for the message. message_ref: type: string x-go-type-skip-optional-pointer: true description: Optional reference ID set by the user for the message. sender: type: string format: phone description: Registered WhatsApp sender number in international format. recipient: type: string format: phone description: WhatsApp recipient phone number in international format. content_type: $ref: '#/components/schemas/WhatsappContentType' content: type: object description: Content details for the message. oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/TemplateContent' - $ref: '#/components/schemas/CustomContent' sms_fallback: $ref: '#/components/schemas/SMSFallback' created_at: type: string format: date-time description: Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the message was created on the server. required: - id - sender - recipient - content_type - content - created_at example: id: 6fdae71c-dad7-4c36-9734-a69693ecf3b4 message_ref: optional-ref-123 sender: '14155238886' recipient: '61411122211' content_type: template content: template: name: welcome_new_customer parameters: - Joe created_at: '2021-01-01T00:00:00Z' TooManyRequestsProblem: description: 'HTTP 429 Too Many Requests - Rate limit exceeded. Your client application has sent too many requests in a given amount of time and should retry later. ' type: object allOf: - $ref: '#/components/schemas/ProblemDetails' example: type: https://developers.kudosity.com/reference/errors#too-many-requests title: Too Many Requests detail: Rate limit exceeded status: 429 InternalServerErrorProblem: description: 'This problem occurs when the server encounters an unexpected condition that prevents it from fulfilling the request. Your client application did everything correct. Unfortunately our API encountered a condition that resulted in this problem. ' type: object allOf: - $ref: '#/components/schemas/ProblemDetails' example: type: https://developers.kudosity.com/reference/errors#server-error title: Server Error detail: The server encountered an unexpected error status: 500 InputValidationProblem: description: 'This problem occurs when the request is deemed unprocessable. Your client issued a request that failed validation. Certain validation libraries return multi-errors and cannot be easily parsed into discreet types. This problem type, afforded the provider with the ability to surface all validation errors and negate the need for a trial and error workflow on your side. ' type: object allOf: - $ref: '#/components/schemas/ProblemDetails' - properties: issues: description: An array of issues detected during input validation. type: array x-go-type-skip-optional-pointer: true items: $ref: '#/components/schemas/InputValidationIssue' example: type: https://developers.kudosity.com/reference/errors#input-validation title: Invalid Request detail: Request validation failed status: 400 issues: - name: field_name message: field_name is required TemplateContent: type: object properties: template: $ref: '#/components/schemas/Template' required: - template InputValidationIssue: type: object description: 'An issue detected during input validation. ' properties: name: type: string description: The name of the param or field that failed validation. x-go-type-skip-optional-pointer: true code: type: integer description: The internal api specific error code. x-go-type-skip-optional-pointer: true message: description: The error message type: string x-go-type-skip-optional-pointer: true WhatsappListMessageItem: type: object description: Summary representation of a WhatsApp message for list responses. properties: id: type: string description: Unique identifier for the message. message_ref: type: string x-go-type-skip-optional-pointer: true description: Optional reference ID set by the user for the message. campaign_id: type: string x-go-type-skip-optional-pointer: true description: 'UUID of the campaign that produced this message. Omitted when the message is not associated with a campaign. ' sender: type: string format: phone description: Registered WhatsApp sender number in international format. recipient: type: string format: phone description: WhatsApp recipient phone number in international format. content_type: $ref: '#/components/schemas/WhatsappContentType' content: type: object description: Content details for the message. oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/TemplateContent' - $ref: '#/components/schemas/CustomContent' status: $ref: '#/components/schemas/WhatsappMessageStatus' created_at: type: string format: date-time description: Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the message was created on the server. required: - id - sender - recipient - content_type - content - status - created_at example: id: 6fdae71c-dad7-4c36-9734-a69693ecf3b4 message_ref: optional-ref-123 sender: '14155238886' recipient: '61411122211' content_type: template content: template: name: welcome_new_customer parameters: - Joe status: DELIVERED created_at: '2021-01-01T00:00:00Z' campaign_id: 9b2e4c1a-7f3d-4a8b-9c5e-2d1f6a8b3c4d CommonResponseMeta: type: object properties: request: type: object description: Optional metadata (e.g. requestId, traceId) meta: type: object description: Optional pagination, feature flags, etc. UnauthorizedProblem: description: 'HTTP 401 Unauthorized - API authentication failed. The request was rejected because the API key is missing, invalid, expired, or lacks sufficient permissions for this resource. Check your Authorization header and API key configuration. ' type: object allOf: - $ref: '#/components/schemas/ProblemDetails' example: type: https://developers.kudosity.com/reference/errors#unauthorized title: API Authentication Failed detail: Missing or invalid API key in Authorization header. Verify your API key is correct and has the required permissions status: 401 Custom: type: object description: Custom content following the Meta Cloud API guidelines. additionalProperties: true PaginationMeta: title: Pagination Metadata description: 'Pagination metadata for cursor-based pagination. Reusable across all paginated API endpoints. ' type: object required: - type - has_next - has_prev properties: type: type: string description: The pagination strategy being used. enum: - cursor example: cursor x-oapi-codegen-extra-tags: valid: required next_cursor: type: - string - 'null' description: Cursor to fetch the next page of results. Omitted if there are no more results. example: MTIzNDU2 x-oapi-codegen-extra-tags: json: next_cursor,omitempty prev_cursor: type: - string - 'null' description: Cursor to fetch the previous page of results. Omitted if on the first page. example: MTIzNDkw x-oapi-codegen-extra-tags: json: prev_cursor,omitempty has_next: type: boolean description: Indicates whether there are more results available after the current page. example: true x-oapi-codegen-extra-tags: valid: required has_prev: type: boolean description: Indicates whether there are results available before the current page. example: false x-oapi-codegen-extra-tags: valid: required WhatsappListMessagesMeta: type: object description: Metadata for the list messages response including pagination details. properties: pagination: $ref: '#/components/schemas/PaginationMeta' required: - pagination WhatsappGetResponse: type: object properties: id: type: string description: Unique identifier for the message. account_id: type: string description: Account identifier that sent the message. message_ref: type: string x-go-type-skip-optional-pointer: true description: Optional reference ID set by the user for the message. campaign_id: type: string x-go-type-skip-optional-pointer: true description: 'UUID of the campaign that produced this message. Omitted when the message is not associated with a campaign. ' sender: type: string format: phone description: Registered WhatsApp sender number in international format. recipient: type: string format: phone description: WhatsApp recipient phone number in international format. content_type: $ref: '#/components/schemas/WhatsappContentType' content: type: object description: Content details for the message. oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/TemplateContent' - $ref: '#/components/schemas/CustomContent' sms_fallback: $ref: '#/components/schemas/SMSFallback' created_at: type: string format: date-time description: Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the message was created on the server. status: $ref: '#/components/schemas/WhatsappMessageStatus' events: type: array x-go-type-skip-optional-pointer: true x-oapi-codegen-extra-tags: json: events,omitempty description: Array of events showing the message history. items: $ref: '#/components/schemas/WhatsappMessageEvent' required: - id - account_id - sender - recipient - content_type - content - created_at - status example: id: 6fdae71c-dad7-4c36-9734-a69693ecf3b4 account_id: '123123' message_ref: optional-ref-123 campaign_id: 9b2e4c1a-7f3d-4a8b-9c5e-2d1f6a8b3c4d sender: '14155238886' recipient: '61411122211' content_type: template content: template: name: welcome_new_customer parameters: - Joe sms_fallback: message: Welcome Joe! Your account is now active. created_at: '2021-01-01T00:00:00Z' status: DELIVERED events: - event_type: SENT created_at: '2021-01-01T00:00:30Z' details: Message sent to WhatsApp gateway - event_type: DELIVERED created_at: '2021-01-01T00:01:15Z' details: Message delivered to recipient device NotFoundProblem: description: 'This problem occurs when the requested resource could not be found. Your client application tried to access a resource that does not exist (or could not be found). Please review how your users initiated such a request. ' type: object allOf: - $ref: '#/components/schemas/ProblemDetails' example: type: https://developers.kudosity.com/reference/errors#not-found title: Not Found detail: The requested resource was not found status: 404 WhatsappMessageStatus: type: string description: Current status of a WhatsApp message. enum: - QUEUED - SENT - DELIVERED - READ - FAILED WhatsappListMessagesData: type: object description: Container for the list of WhatsApp messages. properties: messages: type: array description: Array of WhatsApp messages. items: $ref: '#/components/schemas/WhatsappListMessageItem' required: - messages CommonSuccessResponse: allOf: - type: object properties: data: type: object description: Success response payload required: - data - $ref: '#/components/schemas/CommonResponseMeta' responses: InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - type: object properties: error: $ref: '#/components/schemas/InternalServerErrorProblem' SuccessResponse: description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonSuccessResponse' - type: object properties: data: $ref: '#/components/schemas/WhatsappResponse' example: data: id: 6fdae71c-dad7-4c36-9734-a69693ecf3b4 message_ref: optional-ref-123 sender: '14155238886' recipient: '61411122211' content_type: template content: template: name: welcome_new_customer parameters: - Joe created_at: '2021-01-01T00:00:00Z' request: {} meta: {} NotFoundErrorResponse: description: Not Found content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - type: object properties: error: $ref: '#/components/schemas/NotFoundProblem' TooManyRequestsErrorResponse: description: Too Many Requests content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - type: object properties: error: $ref: '#/components/schemas/TooManyRequestsProblem' ListWhatsappMessagesSuccessResponse: description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonSuccessResponse' - type: object properties: data: $ref: '#/components/schemas/WhatsappListMessagesData' meta: $ref: '#/components/schemas/WhatsappListMessagesMeta' example: data: messages: - id: 6fdae71c-dad7-4c36-9734-a69693ecf3b4 message_ref: optional-ref-123 sender: '14155238886' recipient: '61411122211' content_type: template content: template: name: welcome_new_customer parameters: - Joe status: DELIVERED created_at: '2021-01-01T00:00:00Z' request: {} meta: pagination: type: cursor next_cursor: MTIzNDU2 prev_cursor: null has_next: true has_prev: false GetWhatsappSuccessResponse: description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonSuccessResponse' - type: object properties: data: $ref: '#/components/schemas/WhatsappGetResponse' example: data: id: 6fdae71c-dad7-4c36-9734-a69693ecf3b4 account_id: '123123' message_ref: optional-ref-123 sender: '14155238886' recipient: '61411122211' content_type: template content: template: name: welcome_new_customer parameters: - Joe sms_fallback: message: Welcome Joe! Your account is now active. created_at: '2021-01-01T00:00:00Z' status: DELIVERED events: - event_type: SENT created_at: '2021-01-01T00:00:30Z' details: Message sent to WhatsApp gateway - event_type: DELIVERED created_at: '2021-01-01T00:01:15Z' details: Message delivered to recipient device request: {} meta: {} InputValidationResponse: description: Input Validation Error content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - type: object properties: error: $ref: '#/components/schemas/InputValidationProblem' UnauthorizedErrorResponse: description: Unauthorized content: application/json: schema: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - type: object properties: error: $ref: '#/components/schemas/UnauthorizedProblem' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: 'All API requests require your API credentials, you will find them once logged into your account on the SETTINGS page. Scroll down to API Settings to find your API key. '