Introduction

Welcome to the Social25 Chat API. This platform allows to centralize the communication with customers of different social media platforms. Currently our system supports the following platforms:

WhatsApp
Facebook Messenger
Kik
WeChat
Twitter
Line
Telegram

Request access

Since the Social25 API is not public, it is required to request an access token and a new test tenant. The request can be done by sending us an email at support@gen25.com.

Authentication

# With shell, you can just pass the correct header with each request
curl -X GET \
  https://social25.herokuapp.com/api/v1.0/tenants/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

Social25 uses Oauth2 authentication. To register for a new key, email us at support@gen25.com

Authorization: yoursocial25token

You must replace yoursocial25token with your personal API key.

Tenants

Tenant is the business representation in our system.

GET | Tenant

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "count": 1,  // The total count of results
    "next": null,  // Url for the next page
    "previous": null,  // Url for the previous page
    "results": [
        {
            "id": "007be0e1-6c95-4843-8673-a76a479266f8",  // Uuid of the tenant
            "name": "Gen25",
            "company_logo": "http://some_url.sgv", // Company logo url
            "settings": {
                "pusher": {   // Tenant specific pusher configuration
                    "public_key": "8f39ad825d7",
                    "cluster": "eu"
                }
            },
            "tags": [],  // Tags that associated with this tenant conversations.
            "agent": {  // Agent requesting the data
                "id": "f03e7882-e48e-42b9-b0a2-e7af7a662c04",  // Uuid of the user
                "username": "agent_username",
                "first_name": "First name",
                "last_name": "Last name",
                "type": "HUMAN", // Available options HUMAN or AUTOMATED
                "is_manager": false,  // Specifies a diferent set of permissions
                "is_staff": true,
                "is_active": true,
                "timezone": "Europe/Amsterdam",  // Agent timezone
                "profile_picture": {
                    "url": "http://some_url.jpg",
                    "etag": "0f783cf0",
                    "type": "upload",
                    "bytes": 110718,
                    "width": 960,
                    "format": "jpg",
                    "height": 958,
                    "version": 1510149500,
                    "public_id": "jo86djq2",
                    "signature": "91724341cdccc27f",
                    "created_at": "2017-11-08T13:58:20Z",
                    "secure_url": "https://some_url.jpg",
                    "placeholder": false,
                    "resource_type": "image",
                    "original_filename": "5e0fc0ddb55f02c"
                },
                "pusher_channel": "channel-name",  // Pusher private channel name
                "tenant_id": "007be0e1-6c95-4843-8673-a76a479266f8",  // Uuid of the tenant
                "is_online": false
            },
            "pusher_channel": "channel-name", // Pusher presence channel name
            "agents": null,
            "dispatch_style": 1,  // How the messages are distributed
            "platforms": [  // All the available social media channels of the tenant
                {
                    "id": 1,
                    "platform": "facebook",
                    "name": "Facebook page name",
                    "page_id": "1",
                    "app_secret": "secret",
                    "page_token": "token",
                    "callback_url": "https://callback_url",
                    "data": null
                },
                {
                    "id": 2,
                    "platform": "messagebird",
                    "name": "Messagebird channel name",
                    "page_id": "1",
                    "app_secret": "secret",
                    "page_token": "token",
                    "callback_url": null,
                    "data": {
                        "channel_subtype": "line"
                    }
                },
                {
                    "id": 3,
                    "platform": "telegram",
                    "name": "Telegram channel name",
                    "page_id": "",
                    "app_secret": "",
                    "page_token": "token",
                    "callback_url": null,
                    "data": null
                },
                {
                    "id": 4,
                    "platform": "kik",
                    "name": "Kik channel name",
                    "page_id": "1",
                    "app_secret": "",
                    "page_token": "token",
                    "callback_url": null,
                    "data": null
                },
                {
                    "id": 5,
                    "platform": "whatsapp",
                    "name": "Whatsapp channel name",
                    "page_id": "1",
                    "app_secret": "",
                    "page_token": "token",
                    "callback_url": null,
                    "data": null
                }
            ]
        }
    ]
}

This endpoint retrieves the tenant configuration.

HTTP Request

GET https://social25-dev.herokuapp.com/api/<VERSION>/tenants/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.

Agents

Agents are all the users registered as employees of a tenant, that reply to messages posted by clients.

GET | All Agents

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/agents/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "count": 1,  // The total count of results
    "next": null,  // Url for the next page
    "previous": null,  // Url for the previous page
    "results": [
        {
            "id": "4b550eaa-24d8-4632-b7d0-988a6e268aff",  // Uuid of the user
            "username": "agente_username",
            "first_name": "First name",
            "last_name": "Last name",
            "type": "HUMAN",  // Available options HUMAN or AUTOMATED
            "is_manager": true,
            "is_staff": true,
            "is_active": true,
            "timezone": "Europe/Amsterdam",  // Agent timezone
            "profile_picture": {
                "url": "http://some_url.jpg",
                "etag": "0f78083bedd19f3cf0rrrr",
                "type": "upload",
                "bytes": 110718,
                "width": 960,
                "format": "jpg",
                "height": 958,
                "version": 1510149500,
                "public_id": "jo868erh2x6djq2vx5ycq",
                "signature": "917243d68ee411b76d2327fwewee",
                "created_at": "2017-11-08T13:58:20Z",
                "secure_url": "https://some_url.jpg",
                "placeholder": false,
                "resource_type": "image",
                "original_filename": "5e0fc04f02c"
            },
            "pusher_channel": "channel-name",   // Pusher private channel name
            "tenant_id": "d30f8db5-e111-4a53-85ce-1e46cece9be6",  // Uuid of the tenant
            "is_online": false
        }
    ]
}

This endpoint retrieves all the agents connected to the specified tenant.

HTTP Request

GET https://social25-dev.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/agents/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.

POST | Agent

curl -X POST \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/agents/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "first_name": "Alen",
    "last_name": "D.",
    "type": 0,
    "is_superuser": false,
    "is_staff": false,
    "is_active": false,
    "timezone": "Europe/Amsterdam",
    "pusher_channel": "channel-name"
}'

{
    "first_name": "Alen",
    "last_name": "D.",
    "type": 0,  // Available types: HUMAN = 1, AUTOMATED = 1
    "is_superuser": false,
    "is_staff": false,
    "is_active": false,
    "timezone": "Europe/Amsterdam",  // Agent timezone
    "pusher_channel": "channel-name"
}

{
    "id": "46fbc862-427a-49fa-b542-c79818ab5e84",
    "username": "",
    "first_name": "Alen",
    "last_name": "D.",
    "type": "HUMAN",
    "is_manager": false,
    "is_staff": false,
    "is_active": false,
    "timezone": "Europe/Amsterdam",
    "profile_picture": null,
    "pusher_channel": "channel-name",
    "tenant_id": "007be0e1-6c95-4843-8673-a76a479266f8",
    "is_online": false
}

This endpoint creates a new agent.

HTTP Request

POST https://social25-dev.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/agents/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.

PUT | Agent

curl -X PUT \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/agents/<AGENT_ID>/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "username": "alen.d"
  }'

{
    "username": "alen.d"
}

{
    "id": "46fbc862-427a-49fa-b542-c79818ab5e84",
    "username": "",
    "first_name": "Alen",
    "last_name": "Mana",
    "type": "HUMAN",
    "is_manager": false,
    "is_staff": false,
    "is_active": false,
    "timezone": "Europe/Amsterdam",  // Agent timezone
    "profile_picture": null,
    "pusher_channel": "channel-name",
    "tenant_id": "007be0e1-6c95-4843-8673-a76a479266f8",
    "is_online": false
}

This endpoint edits an existing agent.

HTTP Request

PUT https://social25-dev.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/agents/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
agent_id	None	true	Uuid value that represents the agent in the system.

Conversation

Conversation is a case that is created when a client messages the business in one of the social media platforms.

GET | Conversations

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "count": 1,  // The total count of results
    "next": null,  // Url for the next page
    "previous": null,  // Url for the previous page
    "results": [
        {
            "id": "13e72bad-2ac1-44cc-8a4a-34a0e19416ef",
            "flow": "SERVICE",  // Possible flows: SERVICE, SURVEY, AUTOMATED, ...
            "state": "OPEN",  // Possible conversation states: OPEN, CLOSED, ...
            "created": "2018-09-10T12:30:28.431583",
            "agent_id": null,  // If the conversation is assigned to an agent this is filled in with the agent uuid
            "user": {
                "id": "dafb669e-d201-4b38-a992-bdafb18a1e2f",
                "username": "agent_username",
                "first_name": "Alen",
                "last_name": "D.",
                "phone_number": null,
                "gender": "male",
                "profile_picture": {
                    "url": "http://some_url.jpg",
                    "etag": "0593731e1fc9478ed43",
                    "tags": [],
                    "type": "private",
                    "bytes": 37915,
                    "width": 604,
                    "format": "jpg",
                    "height": 453,
                    "version": 1536582635,
                    "public_id": "Facebook/profile_images/1234",
                    "signature": "555",
                    "created_at": "2018-09-10T12:30:35Z",
                    "secure_url": "https://some_url.jpg",
                    "placeholder": false,
                    "resource_type": "image"
                }
            },
            "platform": {
                "source": "facebook",
                "name": "Facebook page name",
                "supports_media_captions": false
            },
            "comments": null,
            "tags": [],
            "last_message": {
                "id": "942039a0-ed51-4380-90c7-d2f5667c00b6",
                "agent_id": null,
                "conversation_id": "1ad34ef9-31f0-4479-b683-c012590rcbd7",
                "timestamp": "2018-10-25T08:06:42",
                "modified_timestamp": "2018-10-25T08:06:43.730595",
                "type": "EVENT",  // Possible message types: TEXT, IMAGE, ...
                "status": "RECEIVED",  // Current status of the message
                "outbound": false,
                "text": null,
                "auxiliary_data": "{'title': 'Extra data'}",
                "file": null,
                "file_type": null,
                "media_title": null,
                "mime_type": null
            },
            "has_expired": "116 05:19:39.788243"
        }
    ]
}

This endpoint retrieves all the open conversations of the tenant.

HTTP Request

GET https://social25-dev.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
state	None	false	Return conversations in specified state instead of open & auto_bot. Possible states: open, closed, auto_bot, expired, blocked.

GET | Conversation details

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/details \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "id": "acd8861e-c68c-4189-b329-f6aaad1847c1",
    "flow": "SERVICE",
    "state": "OPEN",
    "created": "2018-09-10T12:30:28.431583",
    "agent_id": null,
    "user": {
        "id": "a6360701-ff6c-4572-88d6-23e1aa5fbe4e",
        "username": "agent_username",
        "first_name": "Allen",
        "last_name": "D.",
        "phone_number": null,
        "gender": "male",
        "profile_picture": {
            "url": "http://some_url.jpg",
            "etag": "059373bc1f3f3fed43",
            "tags": [],
            "type": "private",
            "bytes": 37915,
            "width": 604,
            "format": "jpg",
            "height": 453,
            "version": 1536582635,
            "public_id": "Facebook/profile_images/1234",
            "signature": "5711878b88a4348a081762",
            "created_at": "2018-09-10T12:30:35Z",
            "secure_url": "https://some_url.jpg",
            "placeholder": false,
            "resource_type": "image"
        }
    },
    "platform": {
        "source": "facebook",
        "name": "Facebook page name",
        "supports_media_captions": false
    },
    "comments": null,
    "tags": [],
    "last_message": {
        "id": "6077c61d-6ded-4f72-9a12-6d2bd92f4564",
        "agent_id": null,
        "conversation_id": "34300ef1-baf2-5b65-9124-1a6b6666aa92",
        "timestamp": "2018-10-25T08:06:42",
        "modified_timestamp": "2018-10-25T08:06:43.730595",
        "type": "EVENT",
        "status": "RECEIVED",
        "outbound": false,
        "text": null,
        "auxiliary_data": "{'title': 'Get Started'}",
        "file": null,
        "file_type": null,
        "media_title": null,
        "mime_type": null
    },
    "has_expired": "116 06:25:09.225474"
}

This endpoint retrieves a specific conversation.

HTTP Request

GET https://social25-dev.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID/details/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

PUT | Update Conversation State

curl -X PUT \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/details/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "action": "change_state",
    "state": 0,
    "custom_data": {
        "bot_outcome": "closed_lost"
    }
  }'

{
  "action": "change_state",
  "state": 0,
  "custom_data": {
    "bot_outcome": "closed_lost"
  }
}

{
    "id": "acd8861e-c68c-4189-b329-f6aaad1847c1",
    "flow": "SERVICE",
    "state": "OPEN",
    "created": "2018-09-10T12:30:28.431583",
    "agent_id": null,
    "user": {
        "id": "a6360701-ff6c-4572-88d6-23e1aa5fbe4e",
        "username": "agent_username",
        "first_name": "Allen",
        "last_name": "D.",
        "phone_number": null,
        "gender": "male",
        "profile_picture": {
            "url": "http://some_url.jpg",
            "etag": "059373bc1f3f3fed43",
            "tags": [],
            "type": "private",
            "bytes": 37915,
            "width": 604,
            "format": "jpg",
            "height": 453,
            "version": 1536582635,
            "public_id": "Facebook/profile_images/1234",
            "signature": "5711878b88a4348a081762",
            "created_at": "2018-09-10T12:30:35Z",
            "secure_url": "https://some_url.jpg",
            "placeholder": false,
            "resource_type": "image"
        }
    },
    "platform": {
        "source": "facebook",
        "name": "Facebook page name",
        "supports_media_captions": false
    },
    "comments": null,
    "tags": [],
    "last_message": {
        "id": "6077c61d-6ded-4f72-9a12-6d2bd92f4564",
        "agent_id": null,
        "conversation_id": "34300ef1-baf2-5b65-9124-1a6b6666aa92",
        "timestamp": "2018-10-25T08:06:42",
        "modified_timestamp": "2018-10-25T08:06:43.730595",
        "type": "EVENT",
        "status": "RECEIVED",
        "outbound": false,
        "text": null,
        "auxiliary_data": "{'title': 'Get Started'}",
        "file": null,
        "file_type": null,
        "media_title": null,
        "mime_type": null
    },
    "has_expired": "116 06:25:09.225474"
}

This endpoint can be used to update conversation states. Conversation states can be used to prevent Social25 from pushing messages to Salesforce if a bot is in control of the conversation for example. You can even decide with conversation state you would like to be the default state for your platform. Conversations can have several status:

Code	Status	Description
0	OPEN	This is the default state for all conversations, all messages will be pushed to Salesforce.
1	EXPIRED	The expired state represents a conversation that can not be used anymore.
2	AUTO_BOT	This is the default state if you're platform has a bot integrated as first point of contact. All messages that are received while the conversation has this state will not be pushed to Salesforce.
3	CLOSED	The closed state means that this conversation does not require any action any more from an agent. The next inbound message of the user will switch this conversation back to OPEN.

Make an API call with the integer value of the status you would like to set the conversation state to. Make sure that if you switch the conversation state to OPEN from AUTO_BOT Social25 will not immideatly push data to Salesforce. Only new messages will be pushed to Salesforce. Therefore we recommend to switch the conversation state to OPEN and than sent an outbound message to the user with the information that a agent will pick up there case shortly, this message will than be synced to Salesforce. Since Salesforce utilises the Social25 API for loading message you will be able to see the complete history in the chat window.

The custom_data field can be stored to store and JSON data indefinitly on the conversation, this data will be added to the auxiliary data in Salesforce.

HTTP Request

PUT https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/details/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

DELETE | Conversation

curl -X DELETE \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversation/<CONVERSATION_ID>/delete/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "messages": {
        "destroyed_message_ids": ["639972bf-fbda-46f5-94fe-541a8a0f25e3", ],
        "destroyed": true
    },
    "conversations": {
        "destroyed_conversation_ids": ["18a7712d-396c-413a-8291-2de8ff611942", ],
        "destroyed": true
    },
    "sucess": true
}

This endpoint deletes a specific conversation and all the messages associated with it.

HTTP Request

DELETE https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversation/<CONVERSATION_ID>/delete/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

GET | Conversation tags

curl -X DELETE \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/tags/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "tags": ["tag1", "some_other_tag"]
}

This endpoint deletes a specific conversation and all the messages associated with it.

HTTP Request

GET https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/tags/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.

POST | Initiate Conversations V1

curl -X PUT \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/initiate_conversation/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "platform_id": "<PLATFORM_ID>",
    "user_identifier": "+31611122233"
  }'

{
    "platform_id": "<PLATFORM_ID>",
    "user_identifier": "+31611122233"
}

{
  "conversation_id": "ad917e7d-e169-45e3-8dda-ad1121416eca",
  "user_id": "ad917e7d-e169-45e3-8dda-ad1121416eca"
}

This endpoint has been DEPRECATED Please see V2

Initiate a conversation with a supported channel. At the moment only WhatsApp for Business and Whatsapp Broker channels are supported. This API call will provide you with a conversation id that you can then use in the Media HSM calls or in Salesforce to initiate a chat window.

HTTP Request

GET https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/initiate_conversation/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.

POST | Initiate Conversations V2

curl --request POST \
  --url https://social25.herokuapp.com/api/v1.0/tenants/<TENANT_ID>/conversations/bulk/ \
  --header 'Authorization: Bearer yoursocial25token' \
  --header 'Content-Type: application/json' \
  --data '[{
    "platform_id": "<PLATFORM_EXTERNALID>",
    "user_identifier": "+31699882233"
},{
    "platform_id": "<PLATFORM_EXTERNALID>",
    "user_identifier": "+31699778833"
}''

[{
    "platform_id": "<PLATFORM_EXTERNALID>",
    "user_identifier": "+31611122233"
}, {
    "platform_id": "<PLATFORM_EXTERNALID>",
    "user_identifier": "+31611122233"
}]

{
  "success": true,
  "records": [
    {
      "conversation_id": "502467d0-1674-52fc-8b0e-80c666df1feb",
      "user_id": "502467d0-1674-52fc-8b0e-80c666df1feb"
    },
    {
      "conversation_id": "96d4066e-b779-5b8b-b7fc-6bee131c6fa5",
      "user_id": "96d4066e-b779-5b8b-b7fc-6bee131c6fa5"
    }
  ]
}

Initiate a conversation with a supported channel. At the moment only WhatsApp for Business, Whatsapp Broker channels and SMS are supported. This API call will provide you with a conversation id that you can then use in the Media HSM calls or in Salesforce to initiate a chat window. This endpoint takes a list of user identifiers and a platform external identifier.

This endpoint expects phone numbers to be in the E.164 format. If a phone number is not formatted according to the E.164 format the assumption will be made that the number is formatted according to the national format. For the formatting and validation of the phone number we will utilise the ISO country code of the platform selected.

The input will be validated and the formatted E.164 number will be stored and used for the creation of the conversation.

HTTP Request

GET https://social25.herokuapp.com/api/v1.0/tenants/<TENANT_ID>/conversations/bulk/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.

Messages

GET | Messages

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/messages/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "d8be1be8-cec8-42cd-80a5-70bba9739fb5",
            "agent_id": "9302b67d-ca92-48ce-bfbf-c29bc15005ab",
            "conversation_id": "863105a6-9c14-4e5f-9165-4265b7da18f0",
            "timestamp": "2018-10-24T11:02:40.475002",
            "modified_timestamp": "2018-10-25T10:59:14.345888",
            "type": "TEXT",
            "status": "READ",  // Current status of the message
            "outbound": true,
            "text": "hello!",
            "auxiliary_data": null,
            "file": null,
            "file_type": null,
            "media_title": null,
            "mime_type": null
        }
    ]
}

This endpoint retrieves all the messages associated with a conversation.

HTTP Request

GET https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/messages/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

POST | Message

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/messages/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "type": "text",
    "text": "Hello!"
  }'

// Text Example
{
    "type": "text",
    "text": "Hello!"
}

// Facebook Message Template Example
{
    "type": "template",
    "attachment": {
        "type": "template",
        "payload": {
            "template_type": "generic",
            "elements": [
                {
                    "title": "Order Confirmation",
                    "image_url": "https://example.com/image.jpg",
                    "subtitle": "Click here to see your complete order",
                    "default_action": {
                        "type": "web_url",
                        "url": "https://example.com/product.html",
                        "webview_height_ratio": "tall"
                    },
                    "buttons":[
                      {
                        "type":"postback",
                        "title":"👍",
                        "payload":"CONFIRM"
                      }, {
                        "type":"postback",
                        "title":"👎",
                        "payload":"DECLINE"
                      }
                        ]
                }
            ]
        }
    }
}

// WhatsApp HSM Example
{
    "components": [
        {
            "parameters": [
                {
                    "text": "Please Reply if possible",
                    "type": "text"
                },
            ],
            "type": "body"
        }
    ],
    "locale": "nl",
    "name": "template_name",
    "namespace": "namespace",
    "temp_id": "a5498d4b-88b2-4a61-82c3-b7144e0c83e5",
    "text": "Populated text of the message template, only needed if you want to show it in the chat window.",
    "type": "MEDIA_HSM"
}

{
    "id": "97341947-58aa-48a9-97c0-26d50ce9f8b0",
    "agent_id": "6f1d9615-3e5f-4055-a9d6-55f4d070749d",
    "conversation_id": "64af9c3b-b9cc-4ca0-b8a7-3d628d43d35c",
    "timestamp": "2019-02-20T07:18:07.067846",
    "modified_timestamp": "2019-02-20T07:18:08.277267",
    "type": "TEXT",
    "status": "SENT",
    "outbound": true,
    "text": "Hello!",
    "auxiliary_data": null,
    "file": null,
    "file_type": null,
    "media_title": null,
    "mime_type": null
}

This endpoints allows to send text, media or any type of supported message to the conversation directly.

Upon calling this endpoint for The WhatsApp for Business API with a media HSM Social25 will validate all contacts by calling the WhatsApp for Business contacts endpoint. It's important to only validate contacts that will actually receive a message which is why this validate is embeded into this endpoint.

HTTP Request

POST https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/messages/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

POST | Message Bulk

curl --request POST \
  --url https://social25-dev.herokuapp.com/api/v1.0/tenants/<TENANT_ID>/conversations/messages/bulk/ \
  --header 'Authorization: Bearer yoursocial25token' \
  --header 'Content-Type: application/json' \
  --data '[{
    "conversation_id": "<CONVERSATION_ID>",
    "type": "media_hsm",
    "locale": "es",
    "name": "welcome_mxm",
    "components": [{
        "type": "body",
        "parameters": [
            { "type": "text", "text": "Please ignore this message" },
            { "type": "text", "text": "I am just testing" }
        ]
    }]
}]'

[{
    // HSM
    "conversation_id": "<CONVERSATION_ID>",
    "type": "media_hsm",
    "locale": "es",
    "name": "welcome_mxm",
    "components": [{
        "type": "body",
        "parameters": [
            { "type": "text", "text": "Please ignore this message" },
            { "type": "text", "text": "I am just testing" }
        ]
    }]
}, {
    // TEXT
    "conversation_id": "<CONVERSATION_ID>",
    "type": "text",
    "text": "Hello!"
}]

{
  "status": "success"
}

This endpoints allows to send text or HSM messages in bulk. In this example we demonstrate HSM but you can also utlise this endpoint with simple text messages.

At the moment this endpoint does not yet return messages identifiers since all messages will be processed async. Message references will be added in a later version.

HTTP Request

POST https://social25-dev.herokuapp.com/api/v1.0/tenants/<TENANT_ID>/conversations/messages/bulk/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.

POST | Upload Media (Image/Documents)

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/mediaupload/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "type": "text",
    "text": "Hello!"
  }'
curl \
  --location \
  --request POST \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/mediaupload/ \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'media_file=@/<path_to_file>'

{
    "path": "13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg",
    "url": "https://s3.eu-central-1.amazonaws.com/social25-acc/13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg",
    "secure_url": "https://social25-acc.s3.amazonaws.com/13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=&X-Amz-Date=20191015T114049Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=",
    "type": "private",
    "title": "WhatsApp_Image.jpeg",
    "mime_type": "image/jpeg",
    "resource_type": "image",
    "bytes": 87723
}

This url is used to upload an media file. The results of this call can be used in the Send Media Message to actually deliver the file.

HTTP Request

POST https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/mediaupload/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

POST | Send Media Message

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/messages/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "conversation_id": "31e427e6-2464-4c7c-b9ee-4dfb78b5e6fc",
    "media_file": { // The output here is the exact output provided by the media upload call
        "path": "13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg",
        "url": "https://s3.eu-central-1.amazonaws.com/social25-acc/13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg",
        "secure_url": "https://social25-acc.s3.amazonaws.com/13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=&X-Amz-Date=20191015T114049Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=",
        "type": "private",
        "title": "WhatsApp_Image.jpeg",
        "mime_type": "image/jpeg",
        "resource_type": "image",
        "bytes": 87723
    },
    "mime_type": "image/png",
    "outbound": true,
    "status": "PREPARED",
    "temp_id": "49f4ca10-17d3-433f-94da-43460cb178e8",
    "text": null,
    "timestamp": "2019-10-15T11:26:21.318Z",
    "type": "IMAGE",
    "count_as_inbound": false
}'

{
    "conversation_id": "31e427e6-2464-4c7c-b9ee-4dfb78b5e6fc",
    "media_file": { // The output here is the exact output provided by the media upload call
        "path": "13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg",
        "url": "https://s3.eu-central-1.amazonaws.com/social25-acc/13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg",
        "secure_url": "https://social25-acc.s3.amazonaws.com/13b1f5a93b974a34a5a28e9c1cf55b75/Platform/outbound/WhatsApp_Image.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=&X-Amz-Date=20191015T114049Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=",
        "type": "private",
        "title": "WhatsApp_Image.jpeg",
        "mime_type": "image/jpeg",
        "resource_type": "image",
        "bytes": 87723
    },
    "mime_type": "image/png",
    "outbound": true,
    "status": "PREPARED",
    "temp_id": "49f4ca10-17d3-433f-94da-43460cb178e8",
    "text": null,
    "timestamp": "2019-10-15T11:26:21.318Z",
    "type": "IMAGE",
    "count_as_inbound": false // Optional parameter that will affect the value of Unread_Messages__c in Salesforce
}

{
    "id": "97341947-58aa-48a9-97c0-26d50ce9f8b0",
    "agent_id": "6f1d9615-3e5f-4055-a9d6-55f4d070749d",
    "conversation_id": "64af9c3b-b9cc-4ca0-b8a7-3d628d43d35c",
    "timestamp": "2019-02-20T07:18:07.067846",
    "modified_timestamp": "2019-02-20T07:18:08.277267",
    "type": "IMAGE",
    "status": "SENT",
    "outbound": true,
    "text": null,
    "auxiliary_data": null,
    "file": null,
    "file_type": null,
    "media_title": null,
    "mime_type": null
}

This endpoints allows to send media / documents to the conversation directly. This can be used after uploading media. You can use the following types:

IMAGE FILE VIDEO AUDIO

HTTP Request

POST https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/messages/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

GET | Failed Syncs

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/messages/failed/?from_time=2021-05-01T00:00:00&till_time=2021-06-01T00:00:00 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
          "id": "259cf67d-a720-4f73-8409-8fa84961ceaa",
          "ext_identifier": "a1f22c46-c052-44a9-b23d-e3350685f791",
          "agent_id": null,
          "tenant_id": "e00e41b1-ead3-4b11-ba52-d1a437adbb13",
          "conversation_id": "1352d4ea-de8d-548d-9e13-8b30505aa552",
          "timestamp": "2021-05-17T13:46:48.184191",
          "modified_timestamp": "2021-05-17T13:46:48.817977",
          "type": "TEXT",
          "status": "RECEIVED",
          "outbound": false,
          "text": "Test",
          "auxiliary_data": null,
          "custom_data": null,
          "file": null,
          "file_type": null,
          "media_title": null,
          "mime_type": null,
          "transcribe_enabled": false,
          "transcribe_in_progress": false,
          "log_message": "INVALID_LOGIN: Invalid username, password, security token; or user locked out."
        }
    ]
}

This endpoint retrieves all messages that didn't sync to Salesforce. This view can be used to investigate what issues occured and why messages aren't being sent.

HTTP Request

GET https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/messages/failed/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
from_time	None	true	A timestamp formatted like this 2021-05-01T00:00:00
till_time	None	true	A timestamp formatted like this 2021-06-01T00:00:00
type	standard	false	Pass salesforce to receive messages in the Heroku_Message__c format.

Messages can be retrieved 15 minutes after they have been received. This because we retry the synchronization several times in the first 15 minutes. There can also not be more than 31 days between the form_time and till_time parameters

GET | HSM

curl -X GET \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversations/<CONVERSATION_ID>/whatsapp_templates/?language=<LANGUAGE_CODE> \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

Query Parameters

Parameter	Default	Required	Description
version	None	true	Api version. Currently allowed 1.0 and 1.1
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.
language_code	None	true	Only supported language codes for message templates. Please refer WhatsApp api.

{
    "nl": [
        {
            "text": "Beste {{1}}, hierbij je ordernummer: {{2}}. Groet {{3}}",
            "category": "Order",
            "name": "order"
        },
        {
            "text": "Beste klant, ...",
            "category": "Client message",
            "name": "klant_message"
        }
    ],
    "namespace": "22481c8a-55a9-42d6-8536-dbf593224e21"
}

This allows the business to retrieve all the approved templates of the selected language_code

POST | HSM

curl -X POST \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/send_bulk_hsm/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "process_sync": true, // Specifies if the bulk send is an asynchronous or synchronous task
    "messages":[{
        "type": "hsm", 
        "to": {
            "phone_number": "31600000000",
            "first_name": "Test",
            "last_name": "Surname"
        }, 
        "from": "31600000001", 
        "locale": "en",
        "name": "template_name",
        "parameters": ["Test", "12324", "Test Surname."]
    }]
}'

This endpoint has been DEPRECATED Please see the Bulk Messaging endpoint

This endpoint allows to send bulk WhatsApp templates to customers asynchronously or synchronously.

POST | Media HSM V1

curl -X POST \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/media_template_hsm/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{
    "process_sync": true, // Specifies if the bulk send is an asynchronous or synchronous task
    "messages":[{
        "type": "template", 
        "to": "31600000000",
        "from": "31600000001", 
        "locale": "en",
        "name": "template_name",
        "components": [{
            "type": "header",
            "parameters": [{
                "type": "image",
                "image": {
                    "link": "http(s)://the-url",
                    "provider": {
                        "name": "provider-name"
                    }
                }
            }]
        }]
    }]
}'

This endpoint has been DEPRECATED Please see the Bulk Messaging endpoint

This endpoint allows to send a WhatsApp HSM media templates to customers asynchronously or synchronously.

Upon calling this endpoint for The WhatsApp for Business API Social25 will validate all contacts by calling the WhatsApp for Business contacts endpoint. It's important to only validate contacts that will actually receive a message which is why this validate is embeded into this endpoint.

Users

DELETE | User

curl -X DELETE \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/user/<USER_ID>/delete/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{  
   "messages":{  
      "destroyed_message_ids":["6077c61d-6ded-4f72-9a12-6d2bd92f4564", ],
      "destroyed":true
   },
   "conversations":{  
      "destroyed_conversation_ids":["94bff8ba-ab8f-4dbc-ace7-d6cd46104a59", ],
      "destroyed":true
   },
   "user":{  
      "destroyed":true
   },
   "success":true
}

This endpoints deletes the user and all his conversations in the system.

HTTP Request

DELETE https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/user/<USER_ID>/delete/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
user_id	None	true	Uuid value that represents the user in the system.

POST | Block User

curl -X POST \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversation/<CONVERSATION_ID>/block/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "message": "OK", 
    "data": {}
}

This endpoints blocks the user on a platform. We use the conversation id to identify which platform we should block the user from.

HTTP Request

POST https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/user/<CONVERSATION_ID>/block/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

Allowed platforms

This feature is active for the following platforms:

Facebook
Twitter
Whatsapp

POST | Unblock User

curl -X POST \
  https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/conversation/<CONVERSATION_ID>/unblock/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token'

{
    "message": "OK", 
    "data": {}
}

This endpoints unblock the user from a platform. We use the conversation id to identify which platform we should unblock the user.

HTTP Request

POST https://social25.herokuapp.com/api/<VERSION>/tenants/<TENANT_ID>/user/<CONVERSATION_ID>/unblock/

Query Parameters

Parameter	Default	Required	Description
id	None	true	Api version.
tenant_id	None	true	Uuid value that represents the tenant in the system.
conversation_id	None	true	Uuid value that represents the conversation in the system.

Allowed platforms

This feature is active for the following platforms:

Facebook
Twitter
Whatsapp

Bots

Customers can integrate their own bots with Social25 utilising our API. We can post webhooks for every inbound message and state changes. This will be posted to a webhook which can be configured per platform.

Webhooks

Social25 HTTP Request

This section describes the conversational steps between Social25 and an external bot. For every message sent by the customer, Social25 will trigger a POST request to the bot client with the following payload (see payload on the right hand side).

{
  "id": "97d647e2-7b4d-4bab-8435-e0cc90de8871",
  "ext_identifier": "f615e90f1afceb70a1291a449c031fda41aed9cf",
  "agent_id": null,
  "tenant_id": "8560cf87-ef70-49b3-9f57-d018c8d64be4",
  "conversation_id": "89710dc0-f7b5-5051-874f-e0be93bb3b58",
  "timestamp": "2021-05-05T09:54:52",
  "modified_timestamp": "2021-05-05T09:54:53.273482",
  "type": "TEXT",
  "status": "RECEIVED",
  "outbound": false,
  "text": "This is the text of the message",
  "auxiliary_data": null,
  "custom_data": null,
  "file": null,
  "file_type": null,
  "media_title": null,
  "mime_type": null,
  "transcribe_enabled": false,
  "transcribe_in_progress": false,
  "error_log": null,
  "chat_user": {
    "id": "89710dc0-f7b5-5051-874f-e0be93bb3b58",
    "username": null,
    "first_name": null,
    "last_name": null,
    "phone_number": "31612345678",
    "gender": null,
    "profile_picture": null
  },
  "platform": "whatsapp"
}

Bot client HTTP Request

The bot client can reply to the conversation using the Messages endpoint.

Errors

This error section is stored in a separate file in includes/_errors.md. Slate allows you to optionally separate out your docs into many files...just save them to the includes folder and add them to the top of your index.md's frontmatter. Files are included in the order listed.

The Social25 API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The user is not properly authenticated.
404	Not Found -- The specified data could not be found.
405	Method Not Allowed -- You tried to access content with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The data requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- Too many requests.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.