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)
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
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
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
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 / 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.
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
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:
Last updated
Was this helpful?
