Intro to Messaging

Wiki ▸ API Reference ▸ Chat ▸ Intro to Messaging

Endpoints

• http://dev.api.shoutit.com/docs/#!/conversations
• http://dev.api.shoutit.com/docs/#!/messages
• http://dev.api.shoutit.com/docs/#!/public_chats (used for listing and creating Public Chats conversations)

Terminology

While working with Shoutit messaging these terms will be often mentioned

• Conversation
• Message
• Message Attachment

Conversation

Chat between two profiles or more. Each conversation has a set of Message objects. Conversations can but not necessary have topic such as a shout.

Conversation Object

Will be returned in all endpoints except in detailed conversation endpoint

{
    "id": "168d6091-7999-4245-9103-325ed7416921",
    "modified_at": 1463750456,
    "api_url": "http://api.shoutit.local/v3/conversations/168d6091-7999-4245-9103-325ed7416921",
    "type": "public_chat",
    "display": {
        "title": "First line display",
        "sub_title": "Second line display",
        "last_message_summary": "Third line display",
        "image": "https://tag-image.static.shoutit.com/21956730963873_477ed080-0a53-4a15-9d02-1795d2e8b875.jpg"
    },
    "location": {
        "country": "AU",
        "postal_code": "4557",
        "state": "Queensland",
        "city": "Sunshine Coast"
    },
    "unread_messages_count": 0,
    "messages_url": "http://api.shoutit.local/v3/conversations/168d6091-7999-4245-9103-325ed7416921/messages",
    "reply_url": "http://api.shoutit.local/v3/conversations/168d6091-7999-4245-9103-325ed7416921/reply"
}

Conversation Detail object

Will be only returned in detailed conversation endpoint GET /conversations/{id}

It has same properties of Conversation object in addition to

{
    "created_at": 1463750456,
    "web_url": "http://local.www.shoutit.com:3000/conversation/168d6091-7999-4245-9103-325ed7416921",
    "app_url": "shoutit://conversation?id=168d6091-7999-4245-9103-325ed7416921",
    "messages_count": 0,
    "creator": {},
    "admins": [
        "477ed080-0a53-4a15-9d02-1795d2e8b875"
    ],
    "profiles": [{}],
    "blocked": [
        "312ac321-0b65-c763-3a57-5647d9c12345"
    ],
    "attachments_count": {
        "profile": 0,
        "media": 0,
        "shout": 0,
        "location": 0
    },
    "about": null
}

• Available conversation types are: about_shout, chat and public_chat. When the conversation is of type about_shout the attribute about will be the shout object.
• profiles and creator will be of type Profile Mini object
• creator can be null when the conversation was created by the system
• profiles has all the conversation participants and doesn't support pagination yet
• location is only available for conversations of type public_chat
• admins and blocked are profile ids
• List of blocked can be fetched using /conversations/{id}/blocked

Message

Single message in a conversation that has either text, attachments or both.

Example

{
        "id": "726ab625-8a4e-413a-b155-3c80ceadab2d", 
        "created_at": 1424888209, 
        "conversation_id": "168d6091-7999-4245-9103-325ed7416921",
        "app_url": "shoutit://conversation?id=168d6091-7999-4245-9103-325ed7416921",
        "profile": {}, 
        "text": "test message",
        "attachments": [],
        "read_by": []
}

• profile can be null when the message was created by the system

Message Attachment

Message Attachments are four types

• Location: location
• Shout: shout
• Profile: profile
• Media: images and videos

Location - Example

{
    "attachments": [
        {
            "location": {
                "latitude": 12.345, 
                "longitude": 12.345
            }
        }
    ]
}

Shout - Example

{
    "attachments": [
        {
            "shout": "{Shout Object}*"
        }
    ]
}

Any attribute other than the id will be ignored when replying. Full Shout Object will be returned.

Profile - Example

{
    "attachments": [
        {
            "profile": "{Profile Object}*"
        }
    ]
}

Any attribute other than the id will be ignored when replying. Full Profile Object will be returned.

Images and Videos- Example

{
    "attachments": [
        {
            "images": ["https://shout-image.static.shoutit.com/image.jpg"],
            "videos": ["{Video Object}"]
        }
    ]
}

Notes for attachments

• It is possible to have more than one attachment in the list.
• Having combinations of location, shout, profile, images and videos in an attachment object is allowed. The API will however treat them as separate attachments. API always returns a list of attachment objects each of a single type: Shout, Location or Media.

i.e. sending this

[
    {
        "location": {},
        "shout": {},
        "profile": {},
        "images": [],
        "videos": []
    }
]

is the same and will be always returned as this

[
    {
        "location": {}
    },
    {
        "shout": {}
    },
    {
        "profile": {}
    },
    {
        "images": [],
        "videos": []
    }
]