Communication Microservice Documentation

The External Communications Microservice enables you easily send messages via various communication channels. Currently, only email functionality is supported and sending email is now seamless and centralized for all our microservices.

Register as a developer via Shopp!ng Dev Portal, navigate to the account section and retrieve your API keys

  • client_id: This is a unique string used to identify your developer account.
  • client_secret: This is your password to our API. It will be used for authentication. Please treat as confidential.

Before you can call the API method, you need to exchange your API key information for an authentication token. This token would be used in subsequent calls to the API. To get your token, you need to make a POST request to https://api.shoppi.ng/oauth/token The following POST parameters have to be defined in your request:

  • service_id: the value of this should be communication
  • client_id: Your API key client ID
  • client_secret: Your API key client secret
  • grant_type: the value of this should be client_credentials

Sample response from the request:

      
      {
        "access_token": "eyJhiUUM5OENCSkdQVUIxMDI3UEJZS0VRVE5PWCIsInVzZXJSb2xlcyI6IiIsImNsaWVudFJvbGVzIj",
        "type": "bearer",
        "expires_in": 1209600
      }
      
  

Your token is the value of access_token. This must be included as an Authorization header in all subsequent requests. e.g Authorization: Bearer eyJhiUUM5OENCSkdQVUIxMDI3UEJZS0VRVE5PWCIsInVzZXJSb2xlcyI6IiIsImNsaWVudFJvbGVzIj

As part of the registration process, you would have provided us with a callback URL with which we inform you about the status of emails you send using this service.
To send an email, send a POST request to https://api.shoppi.ng/communication/api/v1/email/enqueue

Below is a sample body of the request:

contentType=PLAIN_TEXT&personal=Mall&sender=random_developer@example.com&recipient=random_receiver@example.com&subject=Playing&message=Hello%20World
      
  • contentType: The only supported format for now is PLAIN_TEXT.
  • personal: The name that should appear as sender of the email.
  • sender: Your email address.
  • recipient: The email address of the recipient.
  • subject: The subject of the message you wish to send.
  • message: The message you wish to send to the other party.

The system processes your request and returns a transaction reference for the operation you just performed. Your message is then enqueued. Once the system is done processing your email message, it invokes your callback URL with parameters describing the status of the email that was sent.