Knowledge Base

Table of Contents

Proactive-Messaging

What is Proactive-Messaging?

The Proactive-messaging allows enterprises to reach out preemptively to customers ensuring a higher satisfaction and loyalty. Typical use cases include appointment reminders, delivery confirmations, shipping updates, order tracking, etc. With our convenient and secure RESTful API enterprises can send proactive messages to their customers.

What can you do with the Proactive-Messaging API?

Sparkcentral’s Proactive-messaging API allows you to

  • Send messages real-time to your customers for the supported mediums including HSM’s on WhatsApp.
  • Follow up on the status of the sent messages.
  • Retrieve detailed information about the reason of failures.

Rate limit

The Proactive Messaging API is tailor made for real time messages use cases and hence is rate limited as of now to 60 messages/min/organization. Enterprises exceeding these limits will receive an error and will have to send the failed messages again.

What Sparkcentral mediums are supported?

Sparkcentral is committed to supporting the most messaging mediums on the market with the richest set of functionality. Today, you can use Sparkcentral to send proactive messages on the following mediums:

  • WhatsApp
  • MessageBird (SMS)
  • Twilio (SMS)

Metadata

 You can now pass along custom information, that we will store in Sparkcentral. This data can then be exported by using our messages export.

Use-case example:

  • You want to send an appointment confirmation to your customer and pass along a unique identifier. Now, you can download the Messages export from Sparkcentral. And you can learn how many customers are responding to your outbound notification.
 
Example code:
{
    "contact": "+32123456789",
    "text": "This is a message with metadata",
    "medium": "WHATSAPP",
    "channel": "Sparkcentral WA Channel",
    "metadata": {
    "customerID": "ABC123",
    "Source": "IVR"
  }
}  

Getting started with the Proactive API

Access to the Sparkcentral Proactive-messaging endpoints requires access keys. Users with admin level access can generate keys in Settings,Integration & APIs,Rest API Keys.

Authorization

The Proactive-messaging API uses the Client Credential Grant flow of the Oauth 2.0 specification for client authentication and authorization. Clients will be provided a client_id and client_secret to authenticate with Sparkcentral’s authorization server and will receive an access_token to use for API request authorization. The access_token should be used in an authorization header, but optionally can be passed as a query string parameter (see request/response details below). When the access_token expires the API will return a 401 unauthorized. The client can automate this by generating a new access token and replaying the failed request with the fresh access token as documented in the following section.

CLIENT CREDENTIAL GRANT

Retrieve an access_token to make authorized API requests. When the access_token expires, use this endpoint to generate a new token.

REQUEST

$ curl -X POST https://public-api.sparkcentral.com/oauth2/token
-H 'content-type: application/x-www-form-urlencoded' -d
'grant_type=client_credentials&client_id=YOUR_CLIENT_ID_HERE&
client_secret=YOUR_CLIENT_SECRET_HERE&scope=client-read'

or

$ curl -X POST
https://public-api-eu.sparkcentral.com/oauth2/token -H 'content-type:
application/x-www-form-urlencoded' -d
'grant_type=client_credentials&client_id=YOUR_CLIENT_ID_HERE&
client_secret=YOUR_CLIENT_SECRET_HERE&scope=client-read'

ParameterStatusDescription
grant_typerequiredMust be set to client_credentials
client_idrequiredSparkcentral provided client identifier
client_secretrequiredSparkcentral provided client secret
scoperequiredMust be set to client-read

RESPONSE

{ “token_type”: “bearer”, “access_token”: “a1b2c3d4e5f6”, “expires_in”: 43200 } 
ParameterDescription
token_typeThe token type to be used in the authorization header. This will always be bearer for client credentials grant.
access_tokenThe token used to authorize requests. This should be added to requests as an authorization header: Authorization: Bearer a1b2c3d4e5f6. The API will also accept access_token as a query string parameter, however using the authorization header is the preferred method.
expires_inThe number of seconds until the token expires (12 hours)

Proactive-Messaging APIs

SEND PROACTIVE MESSAGE

Send a proactive message.

Example URI

POST /proactive-messaging/

Headers

Content-Type: application/json
Authorization: Bearer <token>

 

Body

{
  "medium": "<medium>",
  "channel": "<channel>",
  "contact": "<contact>",
  "text": "<text>"
}

 

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Send proactive message",
  "type": "object",
  "properties": {
    "medium": {
      "type": "string",
      "description": "The medium you want to use.",
      "enum": [
        "MESSAGEBIRD",
        "TWILIO",
        "WHATSAPP"
      ]
    },
    "channel": {
      "type": "string",
      "description": "The name of the channel. Use one of the Accounts in Settings -> Channels."
    },
    "contact": {
      "type": "string",
      "description": "The reference to a contact. In case of a telephone number it should start with a plus sign. "
    },
    "text": {
      "type": "string",
      "description": "The message you want to send."
    }
  },
  "required": [
    "medium",
    "channel",
    "contact",
    "text"
  ]
}

 

The message is queued for processing. Use the returned correlation id to get the status of the sent message.

Headers

Content-Type: application/json
 

Body

{
  "correlationId": "4f1dba7b-9ef3-11e8-a0f4-175408e41992"
}

All fields are required.

Headers

Content-Type: application/json
Authorization: Bearer <token>
 

Body

{}

Headers

Content-Type: application/json
 

Body

{
  "errors": [
    "channel: must not be blank",
    "contactReference: must not be blank",
    "medium: must not be null",
    "text: must not be blank"
  ]
}

Invalid medium. Medium should be one of “MESSAGEBIRD”, “TWILIO” or “WHATSAPP”.

Headers

Content-Type: application/json
Authorization: Bearer <token>
 

Body

{
  "medium": "INVALID_MEDIUM",
  "channel": "<channel>",
  "contact": "<contact>",
  "text": "<text>"
}

Headers

Content-Type: application/json
 

Body

{
  "timestamp": "2018-01-01T00:00:00.000+0000",
  "path": "/",
  "status": 400,
  "error": "Bad Request",
  "message": "Failed to read HTTP message"
}

Unauthorized: when using an invalid or expired access token.

GET STATUS OVERVIEW

Get the status overview for a sent proactive message.

 

Example URI

GET /proactive-messaging/correlationId

correlationId                 string (required) 

                                             Correlation ID of the sent message

Headers

Authorization: Bearer <token>

Headers

Content-Type: application/json

Body

{
  "correlationId": "44717822-9f05-11e8-b71e-671342217f40",
  "total": 1,
  "statuses": {
    "DELIVERED": 1
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Status overview",
  "type": "object",
  "properties": {
    "correlationId": {
      "type": "string",
      "description": "The correlation id of the sent message.",
    },
    "total": {
      "type": "string",
      "description": "The total number of sent proactive messages."
    },
    "statuses": {
      "type": "object",
      "description": "An overview with the number of messages per status",
      "properties": {
        "PROCESSING": {
          "type": "number",
          "description": "Number of proactive messages that are queued for sending."
        },
        "FAILED": {
          "type": "number",
          "description": "Number of proactive messages that failed to send."
        },
        "SENT": {
          "type": "number",
          "description": "Number of proactive messages that are sent."
        },
        "DELIVERED": {
          "type": "number",
          "description": "Number of proactive messages that are sent and delivered."
        },
        "DELIVERING_FAILED": {
          "type": "number",
          "description": "Number of proactive messages that are sent but could not be delivered."
        }                    
      }
    }
  }
}

Unauthorized: when using an invalid or expired access token.

Unknown correlation Id.

Body

{
  "errors": [
    "Nothing found for this correlation id"
  ]
}

GET STATUS DETAILS

Get the details of the failed messages.

 

Example URI

GET /proactive-messaging/correlationId/FAILED

correlationId                          string (required) 

                                                      Correlation ID of the sent messages

Headers

Authorization: Bearer <token>

Headers

Content-Type: application/json

Body

[
  {
    "status": "FAILED",
    "contact": "+32495123456",
    "reason": "No channel found for medium MESSAGEBIRD"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Overview failed messages",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string",
        "description": "The status of the message"
      },
      "contact": {
        "type": "string",
        "description": "The contact used to send the message to"
      },
      "reason": {
        "type": "string",
        "description": "The reason of failure"
      }
    }
  }
}

 

Body

Unauthorized: when using an invalid or expired access token.

Examples

1. SEND A PROACTIVE TEXT MESSAGE

The example below shows a proactive outbound that can be sent as a text message. Sparkcentral supports text messaging on MessageBird and Twilio. Enterprises are responsible for ensuring that the customers have opted-in for proactive communications.

  • Request

     `curl -X POST https://public-api.sparkcentral.com/proactive-messaging/ --header 'Authorization: Bearer ' -H 'Content-Type: application/json' -d '{ "medium": "MESSAGEBIRD", "channel": "myChannel", "contact": "+32495123456", "text": "Hello world!" }'`
      
      or
      
     `curl -X POST https://public-api-eu.sparkcentral.com/proactive-messaging/ --header 'Authorization: Bearer ' -H 'Content-Type: application/json' -d '{ "medium": "MESSAGEBIRD", "channel": "myChannel", "contact": "+32495123456", "text": "Hello world!" }'`
    
  • Response 200

    {
      "correlationId": "3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66"
    }

2. SEND A PROACTIVE HSM (WHATSAPP)

WhatsApp allows for proactive outbound communication when these are sent as HSM’s (Highly Structured Messages) which are essentially a message template that has been authorized by WhatsApp. These HSM’s will have a name, corresponding text and substitution parameters within the text to make the HSM’s personalized.

Sparkcentral has simplified how enterprises can send out these HSM’s through the use of shorthands which is primarily an inline syntax with the format as below

&((namespace=[[NAMESPACE]] template=[[TEMPLATE NAME]] fallback=[[FALLBACK TEXT]] language=[[LANGUAGE]] body_text=[[VARIABLE1]] body_text=[[VARIABLE2]]))&

Parameter NameParameter DescriptionMandatory?
namespaceUnique code provided by WhatsApp while defining HSM’sMandatory
templateName of the HSM template provided on WhatsApp ManagerMandatory
fallbackWe recommend setting the same value as the Template name hereMandatory
languageThe language in which the HSM should be sent. The language needs to be defined in the WhatsApp ManagerMandatory
body_textThe variable text. There can be 0, 1 or multiple variables in 1 HSM. Per variable, there needs to be a body_text parameter.Mandatory

The language codes can be found on: https://developers.facebook.com/docs/whatsapp/message-templates/creation

For sending the HSM out enterprises should construct the shorthand and send it over in the text field as shown below.

  • Request

     `curl -X POST https://public-api.sparkcentral.com/proactive-messaging/ -H 'Authorization: Bearer ' -H 'Content-Type: application/json' -d '{ "medium": "WHATSAPP", "channel": "myChannel", "contact": "+32495123456", "text": "&((namespace=[[3c860f8b_1ae3_1105_b9ea_647e69aa2d49]] template=[[welcome_customer]] fallback=[[welcome_customer]] language=[[en]] body_text=[[Gregory]] body_text=[[How can I help you?]]))&" }'`
     
     or
     
     `curl -X POST https://public-api-eu.sparkcentral.com/proactive-messaging/ -H 'Authorization: Bearer ' -H 'Content-Type: application/json' -d '{ "medium": "WHATSAPP", "channel": "myChannel", "contact": "+32495123456", "text": "&((namespace=[[3c860f8b_1ae3_1105_b9ea_647e69aa2d49]] template=[[welcome_customer]] fallback=[[welcome_customer]] language=[[en]] body_text=[[Gregory]] body_text=[[How can I help you?]]))&" }'`
    
  • Response 200

    {
          "correlationId": "3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66"
      }

3. GET STATUS OVERVIEW

  • Request

    `curl -X GET https://public-api.sparkcentral.com/proactive-messaging/3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66 -H 'Authorization: Bearer '`
      
     or
      
     `curl -X GET https://public-api-eu.sparkcentral.com/proactive-messaging/3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66 -H 'Authorization: Bearer '`
  • Response 200

    {
      "correlationId": "3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66",
      "total": 1,
      "statuses": {
            "SENT": 1
          }
    }

4. GET STATUS DETAILS

  • Request

    `curl -X GET https://public-api.sparkcentral.com/proactive-messaging/f988bd0f-9f9d-11e8-b23b-7d351b0c7ce9/FAILED -H 'Authorization: Bearer '`
      
      or
      
     `curl -X GET https://public-api-eu.sparkcentral.com/proactive-messaging/f988bd0f-9f9d-11e8-b23b-7d351b0c7ce9/FAILED -H 'Authorization: Bearer '`
  • Response 200

    [
      {
        "status": "FAILED",
        "contact": "+32495123456",
        "reason": ""No channel found for medium MESSAGEBIRD"
      }

Was this article helpful?

You already voted!

We're always happy to help you ❤️!

Did you know you could help us too?

We love feedback from our users. It’s incredibly important for our business. That’s why a positive recommendation from your company could really make a difference!