◾Secured Messaging Gateways (Email/SMS/IM)

The primary goal of this API is to allow Smartico.ai sending of emails and SMS messages without any exposure to the personal and identifiable information (PII) such as phone numbers and email addresses of the end users. Smartico is also can send message to the custom messengers/notification centers/inboxes following the API requirements explained below.

Emails via API supplied by customer

Custom should provide API that accepts the following parameters as HTTP POST JSON Body and protected by "Authorization" header with secret value generated by the customer:

ext_user_id / String / platform user id the way it’s reported to Smartico.ai via integration
from_email_address / String / from email address that should be used in the outgoing email
reply_to_email_address / String / replyTo email address that should be used in the outgoing email
subject / String / Email subject
body / String / HTML email body content
text_body / String / Text variation on the email
email_uid / String / unique email ID on Smartico.ai platform
callback_url / String / HTTP API endpoint to be called when email status is changed
activity_type / String / Optional parameter indicating the activity requesting the mail sending (only present when sending preview or mail to risk/support). If present the platform should use to_email_address to send the mail instead of fetching it from the user profile. Possible values: "preview", "Unknown", "EmailCustomerSupport"
to_email_address / String / Optional parameter indicating the email address to send the mail to (only present if there is activity_type parameter)

{
  "ext_user_id": "hhu234556",
  "from_email_address": "Amazing <[email protected]>",
  "reply_to_email_address": "Amazing <[email protected]>",
  "subject": "The best offer your can find on the market",
  "body": "<html>..........</html>",
  "text_body": "Get the offer.....",
  "email_uid": "ksjhdf3428yqwr8fhjhfkdj",
  "callback_url": "https://api.smartico.ai/......callback",
  "activity_type": "preview",
  "to_email_address":"[email protected]"
}

API should return response as JSON message, always with 200 code:

If mail was accepted
- error_code = 0
- ext_message_id - unique SMS id from the gateway (MUST Have)
If failed
- error_code > 0
- error_message - explain why the request to send email failed

{
  "error_code": 0,
  "ext_message_id": "a540f662-45b3-11ee-be56-0242ac120002"
}

{
  "error_code": 1,
  "error_message": "User was not found"
}

SMS/Viber/WhatsApp via API supplied by customer

Custom should provide API that accepts the following parameters as HTTP POST JSON Body and protected by "Authorization" header with secret value generated by the customer:

ext_user_id / String / platform user id the way it’s reported to Smartico
from_number / String / Optional, if integration supports
body / String / text body content of the message
im_uid / String / unique instant message ID on Smartico platform
callback_url / String / HTTP API endpoint to be called when message status is changed

{
  "ext_user_id": "hhu234556",
  "from_number": "Amazing",
  "body": "Best offer ever",
  "im_uid": "ksjhdf3428yqwr8fhjhfkdj",
  "callback_url" : "https://api.smartico.ai/......callback"
}

API should return response as JSON message, always with 200 code:

If SMS was accepted
- error_code = 0
- ext_message_id - unique SMS id from the gateway
If failed
- error_code > 0
- error_message - describe what is the problem

{
  "error_code": 0,
  "ext_message_id": "a540f662-45b3-11ee-be56-0242ac120002"
}

{
  "error_code": 1,
  "error_message": "User was not found"
}

Custom IM via API supplied by customer

Some platforms have own Notification center, messenger or Popups management system.

Smartico can be integrated with such solutions and provide customisable templates for resources according to the requirements of the .

For example, we can take a stocks trading platform that has own notification center that we will call here "My custom messenger".

You can request from Smartico to define template for such message, and following that you can manage messages based on this template.

In the context of our example we may require that template should have following fields:

body of message
description
title
action (buy/sell) and instrument symbol (e.g. stock)

As soon as resource is created, you can build campaign using "Custom IM" activity.

Technical implementation of "Custom IM" API

Custom should provide API that accepts the following parameters as HTTP POST JSON Body and protected by "Authorization" header with secret value generated by the customer:

ext_user_id / String - platform user id the way it’s reported to Smartico
body / String - text body content of the message
im_uid / String - unique instant message ID on Smartico platform
callback_url / String - HTTP API endpoint to be called when message status is changed
extension (optional) / Object - consists of field name and value that are defined in the custom instant message template (e.g. description, title, action, instrument from our example). Note: The names and the types of the extension fields are configured by Smartico according to customer needs.

{
  "ext_user_id": "hhu234556",
  "from_number": null,
  "body": "Best offer ever",
  "im_uid": "ksjhdf3428yqwr8fhjhfkdj",
  "callback_url" : "https://api.smartico.ai/......callback",
  "extension" : {
    "title": "Microsoft is raising",
    "description": "The bullish trend...",
    "action": "BUY/SELL",
    "instrument": "MSFT",
  }
}

API should return response as JSON message, always with 200 code:

If the custom instant message was accepted
- error_code = 0
- ext_message_id - unique id of message from the gateway
If failed
- error_code > 0
- error_message - describe what is the problem

{
  "error_code": 0,
  "ext_message_id": "a540f662-45b3-11ee-be56-0242ac120002"
}

{
  "error_code": 1,
  "error_message": "User was not found"
}

Process of setting up Custom IM

Define the Required Fields Determine the fields that your Custom IM resource manager should include. In the example provided, the fields were "title", "description", "action", and "instrument", but you are free to define any fields relevant to your use case. Fields can be:
- Simple text fields (e.g., strings)
- Predefined options (limited choices)
- Boolean flags (e.g., yes/no)
- Media assets (e.g., images)
Request Smartico to Enable Your Fields Once you have finalized the list of fields, create a JIRA ticket requesting Smartico to enable them in the system.
Implement API for Receiving Custom IM Requests Develop an API on your side that can accept requests when a Custom IM needs to be sent to a specific user.
Implement Reverse Integration for Status Updates Follow the instructions in the next section to report status updates back to Smartico for each instance of sending a Custom IM.
Register Your API in Smartico BackOffice
- Navigate to "Label \ Instant Messages"
- Create a new Custom IM gateway
- Provide the URL of your API endpoint
- Define 'Authorization' key value for additional protection of HTTP call
- Optionally define HTTP-headers that your API may expect
Create and Deploy a Custom IM Campaign
- Go to "Marketing \ Instant Messages"
- Create a new resource with the type "Custom IM"
- Build a marketing campaign that will send this resource to users

Reverse Integration / Delivery Statuses

Upon customer getting any status update regarding email/sms/custom im deliverability, it should call Smartico.ai API, the API is simple HTTP GET call to an endpoint provided in original request. This is needed for two main reasons

To analyse perforomance of communication channels

To build campaign flows based on the activity in communication channel

Example of request:

https://api.smartico.ai/...../?type=email&ext_message_id=71e92bca-48a8-11ee-be56-0242ac120002&status=delivered&api_key=48a8-11ee-be56-0242

The following parameters should be included:

api_key = api key provided for a customer
type = "email", "sms" or "cim"
ext_message_id = same ext_message_id that was provided to Smartico.ai when sending the communication
status = at text ONLY the following values:
- accepted
- delivered
- failed
- rejected
- complained
- opened
- unsubscribed
- clicked

Response as JSON message, always with 200 code:

{
  "error_code": 0,
}

{
  "error_code": 1,
  "error_message": "email was not found"
}

Last updated 8 days ago

Was this helpful?