{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"5b38e0bd-f97b-4967-abe8-287e7aece429","name":"MMC Public Messaging API","description":"## 👋 Introduction\n\nWelcome to the Message My Customer API. This collection of APIs supports a businesses own systems interacting with the Message My Customer (MMC) platform and the Payemoji service to send and receive messages with Recipients using any of the supported messaging channels.\n\nPayemoji is a Conversational eCommerce Service from Message My Customer Ltd, and we specialise in end user engagement through OMNI Channel Messaging.\n\nThe problem we solve is that businesses struggle to effectively engage customers today e.g., SMS = Fraud, Voice = Calls Screened, Apps = Muted Notifications.  \nOur solution is to enable businesses to engage with their customers through personalised, interactive, and secure notifications & conversations using messaging apps like WhatsApp.\n\nThroughout this document we refer to the Message My Customer platform. Payemoji is a service that utilises and sits on this platform.\n\n### Supporting Documentation\n\n#### MMC Event Notification Webhooks\n\nMMC also supports the calling of Webhooks to push relevant events related to messaging. The implementation of a compliant API/webhook allows your system to receive notifications such as new incoming message notifications. This covers incoming messages from a customer for example. The documentation for this can be found [here](https://documenter.getpostman.com/view/27828347/2sA35LVzmh)\n\n### Glossary of Terms and Actors\n\nThere are a number of terms and participant entities which partake in messaging communication that are important to understand as you go through this API documentation.\n\n##### Message My Customer Platform\n\nThe platform that provides connectivity between a Dialogue-Agent (your system) and Recipients (your Customers)\n\n##### Organisation\n\nAn organisation represents a business or any entity that avails of Payemoji services on the Message My Customer Platform. An example being Acme Inc.\n\n##### Dialogue-Agent\n\nFrom the perspective of the Message My Customer platform your system is a Dialogue-Agent. The platform supports multiple Dialogue-Agents concurrent for a given Organisation. Each represents an endpoint capable of communicating with a recipient using this API.\n\n##### Recipient\n\nA recipient is the enduser with whom you communicate. It can be a customer, employee, user etc. that your business wishes to communicate with.  \nNote: Throughout this documentation we consistently use the term recipient even when that entity is initiating a message.\n\n##### Channel\n\nA channel represents the underlying provider messaging channel that recipients use when interacting with an Organisation. Examples of a Channel are WhatsApp or SMS among others.\n\n##### Channel-Group\n\nA Channel-Group is a collection of Channels. An Organisation can have multiple Channel-Groups and each Channel-Group can have multiple Channels. Typically a Channel-Group will align with a business function such as Support or Sales.  \nA given Channel can only be member of one Channel-Group. The Channels of a Channel-Group are peers and all messages on a Channel-Group are routed to the same Dialogue-Agent for the duration of a Dialogue.\n\n##### Dialogue\n\nYou may think of a Dialogue as a conversation between a Dialogue-Agent and a recipient which has a beginning and an end. It is a period of time during which a Dialogue-Agent has exclusive access** to a recipient such that only it can message that recipient. For the duration of a Dialogue, <u>all</u> incoming messages from the recipient are routed to the Dialogue-Agent owning the active dialogue.\n\n##### Notification\n\nThis is a special type of outbound message sent to a recipient independent of any Dialogue. An example may be an OTP message which is fire-and-forget. A Dialogue does not have to exist for an Notification Message to be sent.\n\n**** Exclusive Access Scope**\n\nThe use of the term _exclusive access_ needs some clarification. To support certain modes of use, Notification messages are allowed to overlap with Dialogue Messaging but two concurrent sources of Dialogue Messaging are not allowed. Thus it represents _exclusive access_ to the Recipient via the Dialogue Messaging API. This allows an Organisation to send a contextual OTP message to a recipient from system-X in the middle of a dialogue between the Recipient and system-Y without violating exclusive access.\n\n## Types of Messaging\n\nThere are two distinct messaging patterns supported by the Message My Customer platform\n\n- Dialogue Messaging\n    \n- Notifications\n    \n\nAs the system supports multiple Dialogue-Agents per organisation and each has the ability to engage in extended _conversations_ (dialogues) with a Recipient, it is necessary to support a mechanism for exclusivity of access. At the same time there are cases where exclusive access** to the recipient is not required. Support for these two patterns of communication necessitates two distinct types of message.\n\nWe shall now look at the concepts which support these patterns in detail.\n\n### Dialogues\n\nAll communication on the Message My Customer platform (with the exception of Notifications) occurs in the context of a Dialogue.\n\nA Dialogue represents a back and forth conversation between a Dialogue-Agent and a Recipient. Ultimately a Dialogue may be initiated by either party, though a Recipient may only initiated a Dialogue with the designated Dialogue-Agent identified in system configuration.\n\nA Dialogue confers exclusive access to a Recipient for the initiating Dialogue-Agent for as long as the dialogue is active. A Dialogue between an Dialogue-Agent and a Recipient exists at a Channel-Group level and allows any member channel to be used to deliver dialogue messages.\n\nThis Dialogue ensures that incoming messages are routed to the intended Dialogue-Agent for the duration of the Dialogue. As such, it creates clarity and prevents the potential for 'cross-chat' resulting in recipient confusion and erroneous behaviour by the Dialogue-Agents.\n\n#### Dialogue Management\n\nAs stated, there can be only one active Dialogue between an Dialogue-Agent and a Recipient on a given Channel-Group at a time. To support this, for outbound (towards the Recipient) communication a Dialogue-Agent <u>must</u> first establish a Dialogue before commencing messaging with a recipient. Just as critically, it must close the Dialogue once the purpose of the dialogue has been achieved.  \nThis management of Dialogues allows multiple Dialogue-Agents to exist and have access to the same set of recipients while maintaining exclusive access to the recipient for a period of time.\n\nThis exclusivity prevents the interlacing of unrelated conversations between agent-functions of an organisation and a recipient which will likely result in confusion on the part of the recipient.\n\nThis places a responsibility on each Dialogue-Agent to manage Dialogues and be a good-citizen by closing Dialogues when appropriate so that other Dialogue-Agents can communicate with the Recipient.\n\n<img src=\"https://content.pstmn.io/4a366128-03cd-4d06-ab5e-4a48b348bab0/aW1hZ2UucG5n\" alt=\"Dialogue-Agent%20initiated%20Dialogue%20Lifecycle%20flow\" width=\"571\" height=\"694\">\n\n### Notifications\n\nNotification messages differ from Dialogue messaging in that they can be sent at any time by any Dialogue-Agents without regard for any in-progress Dialogue. Their purpose is to provide time critical information to the recipient without regard to a platform defined context.\n\nAn example of such a message may be the sending of an OTP, flight or package delivery update where message delivery timing is critical and its purpose is understood by the recipient independent of any ongoing interaction via the Message My Customer Platform with the Organisation.\n\nThey are intended to be unidirectional with no support for the recipient to reply. Indeed, any reply will be routed based on any Dialogue that may exist at the time the Recipient chooses to respond (this will be to the Dialogue-Agent that owns the Dialogue and not necessarily to the one that send the Notification) so some care should be taken in their use.\n\nThe sending of, and status retrieval for, Notification messages through the Message My Customer platform supports omni-channel notification messaging using predefined message templates with dynamic content directly from your organisations systems.\n\n## **Authentication**\n\nThe exposed API uses Oauth2.0 authentication with the associated credentials being provided to your company separately. Should you require access to these credential please contact your companies internal Message My Customer relationship owner who can provide them to you or retrieve them from Message My Customer.\n\n### _**Authenticating**_\n\nThe postman structure is such that you can authenticate at the collection level and the resultant token will be used for subsequent API calls for as long as it is valid.\n\n### _Refresh Token Support_\n\nRefresh tokens are not supported for the _Service Accounts_ configured for clients of the Message My Customer API, and therefore it is essential that you re-authenticate when an Access Token expires.\n\n## Supporting Environmental Variables\n\nThis postman collection comes with a set of environment variables which can help you in making API calls through Postman by configuring the values as required within the collection. The parameterised variables are as follows.\n\n##### Custom variables\n\n| **Variable** | **Description** |\n| --- | --- |\n| channel_id | An identifier for the channel you wish the message to be sent on. The set of Channels and their identifiers supported for your organisation will be provide to you during the setup phase. |\n| msg_template_id | Each message needs to be supported by a specific template. This template identifies the message and is mapping to underlying channels. It also identifies the set of message specific parameterisable values. |\n| recipient_phone_number | A place holder for variable for the recipient identity. It should be populated in e164 format including the _+_ symbol, country code and number with _no_ spaces. eg +3538012345678 |\n| oauth_sa_client_id | The Client Application API identity for your application with permissions to access the API (Oauth 2.0) |\n| oauth_sa_client_secret | The Client Application API secret for your application granting access to the API (Oauth 2.0) |\n\n##### Static '_Variables_'\n\nThe following set of variables are effectively static and should typically not be altered but are parameterised to aid future flexibility. Unless you have been instructed to do so, the following should not be altered from their _Initial Value_. These values should be used in your application when configuring access.\n\n| **Parameter** | **Description** |\n| --- | --- |\n| messaging_base_url | The URL root common to all API resources |\n| oauth_base_url | The URL root for the Oauth 2.0 Auth server used in the Oauth 2.0 Auth URL and Access Token URL construction. |\n| oauth_flow | Internal flow identifier used in the Oauth 2.0 Auth URL and Access Token URL construction. |\n| oauth_sa_scopes | The value for scope to be used in the |\n| last_send_notification_id | A convenience parameter populated on every successful POST Notification. |\n\n### JSON:API\n\nThe schemas of this API conform to the [json:api ](https://jsonapi.org/) conventions. This includes not only the body schema for Requests and Responses but also to our use of query parameters.\n\n##### Accepted data types\n\nThe API uses the `Content-Type` and `Accepts-Type` headers should both should cover json:api data types `application/vnd.api+json`\n\n## 🛟 Help and support\n\nIf you have any questions or suggestions, please don't hesitate to reach out to your Account Manager or message our developer support on [devsupport@messagemycustomer.com](https://mailto:devsupport@messagemycustomer.com) and we will be happy to assist you.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"27828347","team":5222836,"collectionId":"5b38e0bd-f97b-4967-abe8-287e7aece429","publishedId":"2s9Y5bPgDo","public":true,"publicUrl":"https://api-docs.messagemycustomer.com","privateUrl":"https://go.postman.co/documentation/27828347-5b38e0bd-f97b-4967-abe8-287e7aece429","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"A set of API methods supporting omni-channel messaging"},{"name":"title","value":"Message My Customer Messaging Integration API"}],"appearance":{"default":"system_default","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-04-17T18:37:20.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"Message My Customer Messaging Integration API","description":"A set of API methods supporting omni-channel messaging"},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"MMC Public API","id":"e5003cee-14f6-456b-ae9d-d01f261d1e51","owner":"27828347","values":[{"key":"dial_agent_client_secret","value":"SAMPLE-2aO8Q~CG_ayP-McR0f1JD9lNAcJJ72-SAMPLE","enabled":true,"type":"default"},{"key":"dialogue_agent_endpoint","value":"<Enter endpoint path for Dialogue-Agent in current value>","enabled":true,"type":"default"},{"key":"organisation_id","value":"<Enter your organisation id in current value>","enabled":true,"type":"default"},{"key":"channel_id","value":"48","enabled":true,"type":"default"},{"key":"file_id","value":"<Enter your file id in current value>","enabled":true,"type":"default"},{"key":"msg_template_type","value":"<Enter template ID in current value>","enabled":true,"type":"default"},{"key":"recipientType","value":"customers","enabled":true,"type":"default"},{"key":"recipient_phone_number","value":"<Full e164 number incl '+countryCode'>","enabled":true,"type":"default"},{"key":"oauth_sa_client_id","value":"Enter client id in current value","enabled":true,"type":"secret"},{"key":"oauth_sa_client_secret","value":"Enter secret id in current value","enabled":true,"type":"secret"},{"key":"messaging_base_url","value":"https://prod-api.messagemycustomer.com","enabled":true,"type":"default"},{"key":"oauth_base_url","value":"https://login.payemoji.com/login.payemoji.com/oauth2/v2.0","enabled":true,"type":"default"},{"key":"oauth_flow","value":"b2c_1_login","enabled":true,"type":"default"},{"key":"oauth_sa_scopes","value":"https://login.payemoji.com/auth/.default","enabled":true,"type":"default"},{"key":"last_created_dialogue_id","value":"<Autopopulated with latest Create Dialogue id>","enabled":true,"type":"default"},{"key":"last_send_notification_id","value":"79746","enabled":true,"type":"default"},{"key":"last_X-MMC-signature","value":"<Autopopulated with latest POST event>","enabled":true,"type":"default"},{"key":"oauth_user_scopes","value":"https://login.payemoji.com/auth/messaging.channels https://login.payemoji.com/auth/messaging.publisher https://login.payemoji.com/auth/messaging.chats https://login.payemoji.com/auth/admin.directory.customer https://login.payemoji.com/auth/admin.directory.centre https://login.payemoji.com/auth/admin.directory.user https://login.payemoji.com/auth/admin.directory.user.security https://login.payemoji.com/auth/admin.directory.orgunit openid offline_access","enabled":true,"type":"default"},{"key":"agent_id","value":"<Enter agent ID in current value>","enabled":true,"type":"default"},{"key":"channelType","value":"Which channel in the channel group to use [WHATSAPP,SMS]","enabled":true,"type":"default"},{"key":"channelGroupId","value":"<Enter Channel Group ID in current value>","enabled":true,"type":"default"},{"key":"templateId","value":"<Enter template ID in current value>","enabled":true,"type":"default"},{"key":"dialogue_agent_ids","value":"0","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/a5dd249a85423b4336ebdc70b27410bd806e07b6f5d53827b5635dd02bed75df","favicon":"https://res.cloudinary.com/postman/image/upload/v1693558635/team/nbichdwcogv6nmo4ocet.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"MMC Public API","value":"27828347-e5003cee-14f6-456b-ae9d-d01f261d1e51"}],"canonicalUrl":"https://api-docs.messagemycustomer.com/view/metadata/2s9Y5bPgDo"}