Admin loginSmartico.aiTheAffiliatePlatform.com

◾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:

  1. ext_user_id / String / platform user id the way it’s reported to Smartico.ai via integration

  2. from_email_address / String / from email address that should be used in the outgoing email

  3. reply_to_email_address / String / replyTo email address that should be used in the outgoing email

  4. subject / String / Email subject

  5. body / String / HTML email body content

  6. text_body / String / Text variation on the email

  7. email_uid / String / unique email ID on Smartico.ai platform

  8. callback_url / String / HTTP API endpoint to be called when email status is changed

  9. 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"

  10. 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 <noreply@amazing.co>",
  "reply_to_email_address": "Amazing <noreply@amazing.co>",
  "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":"test@amazing.co"
}

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:

  1. ext_user_id / String / platform user id the way it’s reported to Smartico

  2. from_number / String / Optional, if integration supports

  3. body / String / text body content of the message

  4. im_uid / String / unique instant message ID on Smartico platform

  5. 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:

  1. ext_user_id / String / platform user id the way it’s reported to Smartico

  2. body / String / text body content of the message

  3. im_uid / String / unique instant message ID on Smartico platform

  4. callback_url / String / HTTP API endpoint to be called when message status is changed

  5. 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.

{
  "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"
}

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

Response as JSON message, always with 200 code:

{
  "error_code": 0,
}

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

Last updated

Was this helpful?