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

To authorize, use this code:

# 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'

Make sure to replace yoursocial25token with your API key.

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

Authorization: yoursocial25token

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'

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command contains the following data:

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

The above command returns JSON structured like this:

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

The above command contains the following data:

{
    "username": "alen.d"
}

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

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'

The above command returns JSON structured like this:

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

The above command contains the following data:

{
  "action": "change_state",
  "state": 0
}

The above command returns JSON structured like this:

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

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.

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'

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

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

The above command contains the following data:

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

The above command returns JSON structured like this:

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

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.

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'

The above command returns JSON structured like this:

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

The above command contains the following data:

{
    "type": "text",
    "text": "Hello!"
}

The above command returns JSON structured like this:

{
    "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 or media 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 | 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>'

The above command returns JSON structured like this:

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

The above command contains the following data:

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

The above command returns JSON structured like this:

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

Facebook

POST | Generic message

curl -X DELETE \
  https://social25.herokuapp.com/api/<VERSION>/facebook/generic_message/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer yoursocial25token' \
  -d '{  
   "object":"page",
   "entry":[  
      {  
         "id":"23",
         "time":1506685247251,
         "messaging":[  
            {  
               "sender":{  
                  "id":"1"
               },
               "recipient":{  
                  "id":"2"
               },
               "timestamp":1506685247055,
               "message":{  
                  "mid":"mid.$cAACCB4xAlqVk_rTf",
                  "seq":3071,
                  "text":"Hello!"
               }
            }
         ]
      }
   ]
}'

The above command contains the following data:

{  
   "object":"page",  // Because it is a facebook page
   "entry":[  
      {  
         "id":"23",
         "time":1506685247251,
         "messaging":[  
            {  
               "sender":{  // Facebook id of the sender
                  "id":"1"
               },
               "recipient":{  // Facebook id of the recipient
                  "id":"2"
               },
               "timestamp":1506685247055,
               "message":{  // Actual message
                  "mid":"mid.$cAACCB4xAlqVk_rTf",
                  "seq":3071,
                  "text":"Hello!"
               }
            }
         ]
      }
   ]
}

The above command returns JSON structured like this:

{
    "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 allow to send Facebook templates (receipt, button, ...) through our system.

HTTP Request

POST https://social25.herokuapp.com/api/<VERSION>/facebook/generic_message/

WhatsApp

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.

The above command returns JSON structured like this:

{
    "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 allows to send bulk WhatsApp templates to customers asynchronously or synchronously.

POST | Media HSM

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 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'

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

Bot Webhook

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:

  {
        "id": "c2609174-e9e9-42b4-81ec-864289e3da82",  // Social25 internal identifier of the message
        "ext_identifier": "JMoS1Z_XAe99XUYNSZGjTnQzObaZ_LAW4BwV7ecASTzGScXGH4B-UKp04imZfNz9p9nlBMl7XUlSiYT6EvAnWQ",
        "agent_id": null,
        "tenant_id": "97fc666b-4018-4ef7-a14e-63f2aac7ba56",  // Social25 internal identifier of the tenant
        "conversation_id": "b4c7141a-c45a-5bfb-9d0d-03d5f8862f97",  // Social25 internal identifier of the conversation
        "timestamp": "2019-07-09T12:41:25",
        "modified_timestamp": "2019-07-09T12:41:26.112885",
        "type": "TEXT",
        "status": "RECEIVED",
        "outbound": false,
        "text": "Hello",
        "auxiliary_data": null,
        "file": null,
        "file_type": null,
        "media_title": null,
        "mime_type": null,
        "transcribe_enabled": false,
        "transcribe_in_progress": false
    }

Bot client HTTP Request

The bot client can reply to the conversation using the following endpoint:

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.

The body of the request must contain the message type and the actual message

Request body

{
    "type": "text",
    "text": "Hello!"
}

The above request returns JSON structured like this:

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

Errors

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.