openapi: 3.0.1 info: title: Communication Management description: "Process (Aggregator) layer of MADAPI Communication Management. Routes\ \ outbound chat to Clickatell, inbound chat to Genesys, and campaign/insight operations\ \ to the LCS backend via the lcs-connector library." license: name: MADAPI url: https://developers.mtn.com/ version: 3.0.0 - Last updated date:2026-08-12 14:13:46 servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: CommunicationManagement paths: /chat/inboundMessage: post: tags: - CommunicationManagement summary: Receive inbound chat message description: "Records an inbound chat message received from the Genesys backend\ \ system, persisting the message metadata and originating message identifier\ \ so downstream consumers can correlate the event with the corresponding outbound\ \ campaign." operationId: Communication_post_inBoundMessage_chatinboundMessage requestBody: content: application/json: schema: title: InboundMessageRequestBody type: object properties: integrationId: type: string integrationName: type: string event: title: Event type: object properties: moText: type: array items: title: MoText type: object properties: channel: type: string messageId: type: string relatedMessageId: type: string relatedClientMessageId: type: string from: type: string to: type: string timestamp: type: string encryptionKey: type: string whatsapp: title: Whatsapp type: object properties: profileName: type: string charset: type: string content: type: string required: true responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI communication management flows. content: application/json: schema: title: InboundMessageResponse type: object properties: statusCode: type: string statusMessage: type: string supportMessage: type: string integrationId: type: string transactionId: type: string timestamp: type: string _links: title: Link type: object properties: self: title: Self type: object properties: href: type: string "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' deprecated: false /chat/outboundMessageWithMedia: post: tags: - CommunicationManagement summary: Sends message with media reference description: Sends an outbound chat message with an attached media reference to the Clickatell backend system for delivery to the recipient identified in channel.to.id; the backend response code is translated to an HTTP status via ClickatellResponseCode. operationId: Communication_post_outboundMessageWithMedia_chatoutboundMessageW requestBody: content: application/json: schema: title: MessageWithMediaRequest type: object properties: id: type: string type: type: string text: type: string channel: title: Channel type: object properties: id: type: string platform: type: string type: type: string to: title: To type: object properties: id: type: string idType: type: string nickname: type: string from: title: From type: object properties: id: type: string idType: type: string nickname: type: string time: type: string format: date-time messageId: type: string content: type: array items: title: Content type: object properties: contentType: type: string attachment: title: Attachment type: object properties: mediaType: type: string filename: type: string mime: type: string url: type: string required: true responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI communication management flows. content: application/json: schema: title: MessageWithMediaResponse type: object properties: apiMessageId: type: string accepted: type: boolean to: type: string error: title: Error type: object properties: code: type: integer format: int32 description: type: string statusCode: type: string statusMessage: type: string supportMessage: type: string transactionId: type: string timestamp: type: string _links: $ref: '#/components/schemas/za_co_mtn_communication_models_response_Link' "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' deprecated: false /communicationMessage: get: tags: - CommunicationManagement summary: List or find CommunicationMessage objects description: "Retrieves the available filter parameters from the LCS multi-insights\ \ backend; returns pagination metadata via X-Total-Count, X-Result-Count and\ \ X-Limit response headers and surfaces each backend filter option as a TMF\ \ characteristic on the data payload. The 'offset' query parameter is a 1-indexed\ \ page number (offset=N → backend page=N, default 1); 'limit' is the page\ \ size (default 20)." operationId: Communication_get_listCommunicationMessage_communicationMessage parameters: - name: channelId in: header required: false schema: type: string - name: fields in: query required: false schema: type: string - name: limit in: query required: false schema: type: integer format: int32 - name: offset in: query required: false schema: type: integer format: int32 - name: targetSystem in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI communication management flows. content: application/json: schema: $ref: '#/components/schemas/za_co_mtn_communication_models_response_communicationResponse_ComApiResponse' "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' deprecated: false post: tags: - CommunicationManagement summary: Create CommunicationMessage (send campaign or create insight) description: "Polymorphic POST that dispatches on the queryType query parameter:\ \ createInsight submits an insight request to LCS; otherwise the request is\ \ treated as a send-campaign call. Forwards channelId header into the body\ \ when present." operationId: Communication_post_createMessage_communicationMessage parameters: - name: channelId in: header required: false schema: type: string - name: queryType in: header required: false schema: type: string - name: targetSystem in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string requestBody: content: application/json: schema: title: JsonNode type: object required: true responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI communication management flows. content: application/json: schema: title: ComApiResponse type: object properties: statusCode: type: integer format: int32 statusMessage: type: string transactionId: type: string sequenceNo: type: string customerId: type: string supportMessage: type: string data: title: Data type: object properties: id: type: string messageType: type: string frequency: type: string tryTimes: type: string emailIdReference: type: string sendTime: type: string sendTimeComplete: type: string state: type: string supportMessage: type: string characteristic: type: array items: title: CharacteristicResponse type: object properties: name: type: string value: type: string attachment: type: array items: title: AttachmentResponse type: object properties: url: type: string filters: type: array items: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string status: type: string channels: type: array items: type: string channelName: type: string errorMessage: type: string webhookStatus: type: string createdAt: type: string filterCriteria: title: FilterCriteria type: object properties: filters: type: array items: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' deprecated: false /communicationMessage/{id}: get: tags: - CommunicationManagement summary: Retrieve CommunicationMessage by ID description: Retrieves the status of a specific LCS insight request by its identifier; the backend job state (PENDING/COMPLETED/FAILED) is mapped to the TMF CommunicationMessageStateType (inProgress/completed/failed) and any backend errorMessage is surfaced via data.supportMessage. operationId: Communication_get_retrieveCommunicationMessage_communicationMessage parameters: - name: channelId in: header required: false schema: type: string - name: id in: path required: true schema: type: string - name: targetSystem in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI communication management flows. content: application/json: schema: $ref: '#/components/schemas/za_co_mtn_communication_models_response_communicationResponse_ComApiResponse' "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' deprecated: false components: schemas: za_co_mtn_communication_models_inboundmedia_Event: title: Event type: object properties: moText: type: array items: title: MoText type: object properties: channel: type: string messageId: type: string relatedMessageId: type: string relatedClientMessageId: type: string from: type: string to: type: string timestamp: type: string encryptionKey: type: string whatsapp: title: Whatsapp type: object properties: profileName: type: string charset: type: string content: type: string com_mtn_madapi_model_response_communicationLCSResponse_Filter: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string za_co_mtn_communication_models_inboundmedia_Whatsapp: title: Whatsapp type: object properties: profileName: type: string za_co_mtn_communication_models_response_Channel: title: Channel type: object properties: id: type: string platform: type: string type: type: string to: title: To type: object properties: id: type: string idType: type: string nickname: type: string from: title: From type: object properties: id: type: string idType: type: string nickname: type: string time: type: string format: date-time messageId: type: string za_co_mtn_communication_models_response_Link: title: Link type: object properties: self: title: Self type: object properties: href: type: string com_mtn_madapi_model_response_communicationLCSResponse_FilterCriteria: title: FilterCriteria type: object properties: filters: type: array items: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string za_co_mtn_communication_models_response_communicationResponse_AttachmentResponse: title: AttachmentResponse type: object properties: url: type: string za_co_mtn_communication_models_response_Self: title: Self type: object properties: href: type: string com_fasterxml_jackson_databind_JsonNode: title: JsonNode type: object com_mtn_madapi_model_request_communicationLCSRequest_Filter: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string za_co_mtn_communication_models_inboundRes_response_InboundMessageResponse: title: InboundMessageResponse type: object properties: statusCode: type: string statusMessage: type: string supportMessage: type: string integrationId: type: string transactionId: type: string timestamp: type: string _links: title: Link type: object properties: self: title: Self type: object properties: href: type: string za_co_mtn_communication_models_response_Error: title: Error type: object properties: code: type: integer format: int32 description: type: string za_co_mtn_communication_models_response_communicationResponse_CharacteristicResponse: title: CharacteristicResponse type: object properties: name: type: string value: type: string za_co_mtn_communication_models_response_To: title: To type: object properties: id: type: string idType: type: string nickname: type: string za_co_mtn_communication_models_request_outboundmedia_MessageWithMediaRequest: title: MessageWithMediaRequest type: object properties: id: type: string type: type: string text: type: string channel: title: Channel type: object properties: id: type: string platform: type: string type: type: string to: title: To type: object properties: id: type: string idType: type: string nickname: type: string from: title: From type: object properties: id: type: string idType: type: string nickname: type: string time: type: string format: date-time messageId: type: string content: type: array items: title: Content type: object properties: contentType: type: string attachment: title: Attachment type: object properties: mediaType: type: string filename: type: string mime: type: string url: type: string za_co_mtn_communication_models_inboundmedia_MoText: title: MoText type: object properties: channel: type: string messageId: type: string relatedMessageId: type: string relatedClientMessageId: type: string from: type: string to: type: string timestamp: type: string encryptionKey: type: string whatsapp: title: Whatsapp type: object properties: profileName: type: string charset: type: string content: type: string za_co_mtn_communication_models_response_communicationResponse_Data: title: Data type: object properties: id: type: string messageType: type: string frequency: type: string tryTimes: type: string emailIdReference: type: string sendTime: type: string sendTimeComplete: type: string state: type: string supportMessage: type: string characteristic: type: array items: title: CharacteristicResponse type: object properties: name: type: string value: type: string attachment: type: array items: title: AttachmentResponse type: object properties: url: type: string filters: type: array items: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string status: type: string channels: type: array items: type: string channelName: type: string errorMessage: type: string webhookStatus: type: string createdAt: type: string filterCriteria: title: FilterCriteria type: object properties: filters: type: array items: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string za_co_mtn_communication_models_response_communicationResponse_ComApiResponse: title: ComApiResponse type: object properties: statusCode: type: integer format: int32 statusMessage: type: string transactionId: type: string sequenceNo: type: string customerId: type: string supportMessage: type: string data: title: Data type: object properties: id: type: string messageType: type: string frequency: type: string tryTimes: type: string emailIdReference: type: string sendTime: type: string sendTimeComplete: type: string state: type: string supportMessage: type: string characteristic: type: array items: title: CharacteristicResponse type: object properties: name: type: string value: type: string attachment: type: array items: title: AttachmentResponse type: object properties: url: type: string filters: type: array items: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string status: type: string channels: type: array items: type: string channelName: type: string errorMessage: type: string webhookStatus: type: string createdAt: type: string filterCriteria: title: FilterCriteria type: object properties: filters: type: array items: title: Filter type: object properties: column: type: string values: type: array items: type: string operator: type: string za_co_mtn_communication_models_request_outboundmedia_Attachment: title: Attachment type: object properties: mediaType: type: string filename: type: string mime: type: string url: type: string za_co_mtn_communication_models_response_MessageWithMediaResponse: title: MessageWithMediaResponse type: object properties: apiMessageId: type: string accepted: type: boolean to: type: string error: title: Error type: object properties: code: type: integer format: int32 description: type: string statusCode: type: string statusMessage: type: string supportMessage: type: string transactionId: type: string timestamp: type: string _links: $ref: '#/components/schemas/za_co_mtn_communication_models_response_Link' za_co_mtn_communication_models_response_From: title: From type: object properties: id: type: string idType: type: string nickname: type: string APIError: title: APIError required: - statusCode - statusMessage type: object properties: statusCode: type: string description: Error status code example: "400" statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z path: type: string description: API endpoint path where the error occurred example: /api/v1/resource method: type: string description: HTTP method of the request that caused the error example: POST downstreamStatusCode: type: string description: Downstream service error code if applicable description: Generic MADAPI error response structure example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z za_co_mtn_communication_models_inboundmedia_InboundMessageRequestBody: title: InboundMessageRequestBody type: object properties: integrationId: type: string integrationName: type: string event: title: Event type: object properties: moText: type: array items: title: MoText type: object properties: channel: type: string messageId: type: string relatedMessageId: type: string relatedClientMessageId: type: string from: type: string to: type: string timestamp: type: string encryptionKey: type: string whatsapp: title: Whatsapp type: object properties: profileName: type: string charset: type: string content: type: string za_co_mtn_communication_models_request_outboundmedia_Content: title: Content type: object properties: contentType: type: string attachment: title: Attachment type: object properties: mediaType: type: string filename: type: string mime: type: string url: type: string securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://api.mtn.com/v1/oauth/access_token scopes: {} Bearer: type: http description: Bearer token received from OAuth2.0 authentication with the MADAPI scheme: bearer bearerFormat: JWT