API Introduction

Our Tellody API is based on HTTP REST calls. Users can use their Tellody account to obtain instant access to our API, via which each user can easily integrate our messaging services and features with your website or any other software solution in any preferred language.

Caution: Tellody is not responsible for recovering any information that is deleted through our API. Please make sure that all API calls contain values that are checked first.

User authentication is not part of each separate API call, so the authentication request needs to run separately and prior to any other call to enable access to the functionality provided via the API. The authentication should preceed from any following API request or in case of executing a set of consecutive requests a single authentication request needs to be performed just before executing the first request of the set. 

HTTP Requests

All API requests are using the header: "application/json".

Also, all requests have a common URL form. The part of the command includes all relevant path variables and attributes of the API call to be executed.

URL Description
https://app.tellody.com/CampaignCloud/<command> Common form of the request URL

Sample Request

Below is a typical example showing a generic flow of requests

PythonOther


#Retrieving the XSRF Token needed for Session
pingResponse = my_session.get("https://app.tellody.com/CampaignCloud/RememberMeController/ping")

#Import the X-XSRF-Token returned from RememberMeController/ping into the request headers
xsrfToken = pingResponse.headers.get("X-XSRF-TOKEN")

#HTTP request header
header = {"Content-Type" : "application/json", "X-XSRF-TOKEN" : xsrfToken}
#create session
my_session = requests.Session()
#login POST parameters
param = {"username" : username, "password" : password, "remember-me" : stay_logged}
#Request 1: Authenticaion (POST)
my_session.post("https://app.tellody.com/CampaignCloud/login", headers=header, data = param)
#After login, any other request can be executed below consecutively
contactData = {
   "subscriber":{
      "email":"This email address is being protected from spambots. You need JavaScript enabled to view it.",
      "firstName":"Thomas"
    }
}
#Request 2: Create contacts (POST)
my_session.post("https://app.tellody.com/CampaignCloud/Subscription", header, contactData)
#Request 3: Retrieve contacts (GET)
my_session.get("https://app.tellody.com/CampaignCloud/Subscription", headers=header)

Responses

By default, all responses are sent in JSON format. The responses vary depending on the type of the request. POST requests usually return and id (e.g. the id of a message after its creation).PUT and DELETE requests return an outcome which can be "OK", null or "Error" to determine whether each request was executed successfully. In case null is returned, this indicates that the targeted element does not exist in the system. GET requests usually return the details of an element or a list of elements with their id and attributes. Below is a sample response from a typical PUT request.
{
  { 
   "outcome":"OK",
   "id":null,
   "data":null
   }
}

Errors

In case of an error, the system may return "Error" as a value for the attribute outcome or an HTTP error response (e.g. HTTP 401 - Unauthorized). In case the outcome returns "Error", the id attribute returns a string describing what went wrong.

Sample Response

Below is an example of a response in case of error.
{
   "outcome":"Error",
   "data":null,
   "id":"Error: Validation failed for classes [com.msensis.campaign.entity.Subscription] during update time for groups [javax.validation.groups.Default, ]\nList of constraint violations:[\n\tConstraintViolationImpl{interpolatedMessage='The msisdn and the CountryCode must be both null or have both values', propertyPath=, rootBeanClass=class com.msensis.campaign.entity.Subscription, messageTemplate='The msisdn and the CountryCode must be both null or have both values'}\n\tConstraintViolationImpl{interpolatedMessage='{Phone number is not valid}', propertyPath=msisdn, rootBeanClass=class com.msensis.campaign.entity.Subscription, messageTemplate='{Phone number is not valid}' 
}\n]"
}
Back to Top