Messages

Use the Messages API to retrieve your messages and webchat conversations.

GET /api/v1/messages

Parameters

Param Required Description
token Required The API token generated throught UI interface on swell platform.
team_id Optional Filter messages to show only those from this team_id. Format: (Int) Ex. 5 for one team or 5,139,102 for multiple teams.
location_id Optional Filter messages to show only those from this location_id. Format: (Int) Ex. 3 for one location or 3,7,20 for multiple locations.
contact_id Optional Filter messages to show only those from this contact_id. Format: (Int) Ex. 2 for one contact 2,9,202 for multiple contacts.
status Optional Filter messages to show only those from this status. Format: (String) use Open or Close.
updated_after Optional Defaults to 1 day ago when from_date is not provided. When from_date is present in the request, it will override the updated_after value. Max value 3 days prior to present date. Filter messages to show only those updated after the given date.
from_date *Optional *Required when to_date is present. Format: Y-m-d Filter messages to show only those created between the from_date and to_date dates. Date range cannot exceed 7 days
to_date *Optional *Required when from_date is present. Format: Y-m-d Filter messages to show only those created between the from_date and to_date dates. Date range cannot exceed 7 days
per_page Optional Specify the number of records to return in one request, specified as an integer from 1 to 100. Default 15.
page Optional Specify the number of records to return in one request, specified as an integer from >= 1 . Default 1.

Examples


Request Example

/api/v1/messages?token=0xiZZPW7TTxyLd9j5hXUM4EPfxFmW9uNVOaPOYkryygJT28m4YVjtKNdfdFg


Response

{
    "data": [
        {
            "id": 00000001,
            "contact_id": 3,
            "date_sent": "2019-07-10 16:48:21",
            "text": "Hi!",
            "read": true,
            "status": "Open",
            "origin": null,
            "message_type": "to",
            "contact": {
                "id": 3,
                "name": "Contact 3",
                "phone": "1234567890",
                "email": null,
                "source": "swell",
                "tags": [],
                "locations": [
                    {
                        "id": 00000006,
                        "name": "Location 6"
                    }
                ],
                "country_code": {
                     "short_name": "US", 
                     "code": "+1"
                 }
            },
            "invite_id": 1,
        },
        {
            "id": 00000002,
            "contact_id": 3,
            "date_sent": "2019-07-10 16:48:21",
            "text": "Hi!",
            "read": false,
            "status": "Open",
            "origin": null,
            "message_type": "from",
            "contact": {
                "id": 3,
                "name": "Contact 3",
                "phone": "1234567890",
                "email": null,
                "source": "swell",
                "tags": [],
                "locations": [
                    {
                        "id": 00000006,
                        "name": "Location 6"
                    }
                ],
               "country_code": {
                  "short_name": "US", 
                  "code": "+1"
               }
            },
            "invite_id": null,
            "created_at": "2022-12-01T13:40:50-07:00",
        },
    ],
    "links": {
        "first": "http://swell.test/api/v1/messages?page=1",
        "last": "http://swell.test/api/v1/messages?page=700",
        "prev": null,
        "next": "http://swell.test/api/v1/messages?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 700,
        "path": "http://swell.test/api/v1/messages",
        "per_page": 2,
        "to": 15,
        "total": 10000
    }
}

GET /api/v1/messages/{id}

Parameters

Param Required Description
id Required The id of the message you want to receive.
token Required The API token generated throught UI interface on swell platform.

Examples


Request Example

/api/v1/messages/1?token=0xiZZPW7TTxyLd9j5hXUM4EPfxFmW9uNVOaPOYkryygJT28m4YVjtKNdfdFg


Response

{
    "data": [
        {
            "id": 00000001,
            "contact_id": 3,
            "date_sent": "2019-07-10 16:48:21",
            "text": "Hi!",
            "read": true,
            "status": "Open",
            "origin": null,
            "message_type": "to",
            "contact": {
                "id": 3,
                "name": "Contact 3",
                "phone": "1234567890",
                "email": null,
                "source": "swell",
                "tags": [],
                "locations": [
                    {
                        "id": 00000006,
                        "name": "Location 6"
                    }
                ],
                "country_code": {
                      "short_name": "US", 
                      "code": "+1"
                }
            },
            "invite_id": 1,
        },
        {
            "id": 00000002,
            "contact_id": 3,
            "date_sent": "2019-07-10 16:48:21",
            "text": "Hi!",
            "read": false,
            "status": "Open",
            "origin": null,
            "message_type": "from",
            "contact": {
                "id": 3,
                "name": "Contact 3",
                "phone": "1234567890",
                "email": null,
                "source": "swell",
                "tags": [],
                "locations": [
                    {
                        "id": 00000006,
                        "name": "Location 6"
                    }
                ],
                "country_code": {
                    "short_name": "US", 
                    "code": "+1"
                }
            },
            "invite_id": null,
        },
    ]
}

POST /api/v1/messages

Parameters

Param Required Description
token Required The API token generated throught UI interface on swell platform.
contact_id Required Contacts id or ids array. Format: (Integer or Array).
message Required The text that will be sending in your message. Format: (String).
direction Optional The direction of the message. Format: (String) use outbound or inbound. Default outbound
media_type Optional The origin of the message. Format: (String) use text or multiline. Default text
message_sublines Optional Only used when direction = inbound and origin = custom. Additional separated lines to be included . Format: (Array)(Objects) Max array size: 15

Message Sub-line Object Structure

Param Required Description
body Required The body of the sub-line message. Format: (String) max:1600 characters
line_header Optional The header of the sub-line message. Format: (String) max:255 characters
body_type Optional The sub-line body display type. Format: (String) use success, danger, info, none. Default none
priority Optional The order in which the sub-line is displayed. Format: (Int) between 1-15 Default: Assigned value based on order received.

Examples


Request Example

{
    "token": "3lxeh7XMElKc97lbPNwWKNEBOw9Nzuur7ntfoKwBzh4UboVos0qU5qhFh4nT",
    "contact_id": [1, 2],
    "message": "The text that will be sending in your message",
    "direction": "inbound",
    "origin": "multiline",
    "message_sublines": [
      {
        "body": "The body of the sub-line message",
        "line_header": "Line Header",
        "body_type": "none",
        "priority": 1
      }
    ]
}


Response

{
    "data": [
        {
            "id": 123456,
            "team": null,
            "contact": {
                "id": 1,
                "name": "Contact 1",
                "phone": "1234567890",
                "email": "swell1@swell.com",
                "source": "web chat",
                "tags": [],
                "locations": [
                    {
                        "id": 1,
                        "name": "Location 1"
                    }
                ],
                 "country_code": {
                     "short_name": "US", 
                     "code": "+1"
                     }
            },
            "type": "Sent",
            "text": "The text that will be sending in your message",
            "date_sent": {
                "date": "2019-07-23 18:19:42.026372",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "status": "Open",
            "web_chat": false
            "media_type": "text",
            "message_sublines": []
        },
        {
            "id": 123457,
            "team": null,
            "contact": {
                "id": 2,
                "name": "Contact 2",
                "phone": "1234567891",
                "email": "swell2@swell.com",
                "source": "swell",
                "tags": [],
                "locations": [],
                "country_code": null
            },
            "type": "Received",
            "text": "The text that will be sending in your message",
            "date_sent": {
                "date": "2019-07-23 18:19:42.032700",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "status": "Open",
            "web_chat": false, 
            "media_type": "multiline",
            "message_sublines": [
              {
                "body": "The body of the sub-line message",
                "line_header": "Line Header",
                "body_type": "none",
                "priority": 1
              }
            ]
        }
    ]
}

Count Messages

GET /api/v1/messages/count

Parameters

Param Required Description
token Required The API token generated throught UI interface on swell platform.
team_id Optional Filter count messages to show only those from this team_id. Format: (Int) Ex. 5 for one team or 5,139,102 for multiple teams.
location_id Optional Filter count messages to show only those from this location_id. Format: (Int) Ex. 3 for one location or 3,7,20 for multiple locations.
date Optional Filter count messages to show only those of the current date. format: yyyy-mm-dd.
to_date Optional Filter count messages to show only those up until to_date format: yyyy-mm-dd.
from_date Optional Filter count messages to show only those from from_date format: yyyy-mm-dd.
page Optional Specify the number of records to return in one request, specified as an integer from >= 1 . Default 1.
per_page Optional Specify the number of records to return in one request, specified as an integer from 1 to 100. Default 15.

Examples


Request Example

/api/v1/messages/count?token=0xiZZPW7TTxyLd9j5hXUM4EPfxFmW9uNVOaPOYkryygJT28m4YVjtKNdfdFg


Response

{
    "received": 48,
    "sent": 46
}