Conversation Object

All SMS and Yappy messages which are sent and received from a device, belong to a conversation. A conversation is unique to a sender or group of senders.

Field Type Description
identifier string Unique identifier for the conversation
Example: BF4DF979-86E9-830D-BFC3-7G9F084D237B
recipients object An array of recipients which are participating in the conversation
E164 string A E.164 phone number for the participant
Example: +15626862
contact_name string The name of the participant
Example: Elon Musk
phone_formatted string The E164 phone number formatted for display based on the users chosen locale
Example: (562) 686-2709
avatar_url string The URL of the participant's avatar
Example: https://api.yappy.im/api/avatar/YAPPY
identifier string The identifier of the contact, can be used in conjunction with the Contacts API
Example: BF4DF979-86E9-830D-BFC3-7G9F084D237B
last_message int The max date/time of the last message of the conversation (unix timestamp)
Example: 1448165156010
unread_SMS_count int The number of unread SMS messages in the conversation
Example: 2
unread_Yappy_count int The number of unread Yappy messages in the conversation. If the user viewed the conversation in their normal SMS app, they would read any SMS they received, but not Yappy messages. To view Yappy messages, they would need to open the conversation with Yappy.
Example: 5
has_Yappy bool true if all participants in the conversation have Yappy and the user can send a Yappy message vs SMS to this conversation
Example: true
recipient_last_veiwed_yappy_message int The last date of the most recently viewed Yappy (not SMS) message in the conversation (unix timestamp). This value is useful for indicating up to what point the participants have viewed any sent Yappy messages. If the participants do not have Yappy, or conversation contains to Yappy messages, this value will be null
Example: 1448165156010
scheduled int The number of messages currently scheduled for this conversation
Example: 1
active bool If false the contact has been deleted
Example: true
created int The time the contact was created (unix timestamp)
Example: 1448165156010
modified int The last time this contact record was modified (unix timestamp)
Example: 1448165156010
Example
{
    "identifier": "BF4DF979-86E9-830D-BFC3-7G9F084D237B",
        "recipients": [
            {
                "E164": "+15626862709",
                "phone_formatted": "(562) 686-2709",
                "contact_name": "Elon Musk",
                "avatar_url": "https://api.yappy.im/api/avatar/YAPPY",
                "identifier": "BF4DF979-86E9-830D-BFC3-7G9F084D237B"
            }
        ],
    "last_message": 1448165156010,
    "unread_SMS_count" : 2,
    "unread_Yappy_count" : 0,
    "has_Yappy" : true,
    "recipient_last_veiwed_yappy_message" : 1448165156010,
    "scheduled" = 1,
    "active": true,
    "created": 1448165156010,
    "modified": 1448165156010
}

get-conversations

Get a list of conversations belonging to a device. The device must be a phone to have a conversation.

Call
GET https://api.yappy.im/v1/devices/[device_identifier]/conversations

Request
Field Type Required Description Default Value
device_identifier string Yes The device_identifier of the Device object you would like conversations listed for. This must be passed in the REST URL call, not the querystring parameters.
Example: BF4DF979-86E9-830D-BFC3-7G9F084D237B
page int No The Page number to return (see Pagination)
Example: 2
1
results int No The number of results to return per page (see Pagination)
Example: 500
200
include_names bool No If false, returns only participant identifier and E164 values. This is useful to limit data payload size if you are syncing the contact list locally and don't need the redundant data.
Example: true
true
modified_after int No Return conversations modified after this date (unix timestamp)
Example: 1448165156010
active bool No If true, returns only active contacts
Example: true
False
Response
Field Type Description
conversations Conversation[] Array of Conversation objects
Example: Get Conversations
Request
curl --header 'Access-Token: <your_access_token_here>' \
     https://api.yappy.im/v1/devices/BF4DF979-86E9-830D-BFC3-7G9F084D237B/conversations?page=1&results=200
Response
{
    "conversations": [
        {
           "identifier": "BF4DF979-86E9-830D-BFC3-7G9F084D237B",
             "recipients": [
                    {
                        "E164": "+15626862709",
                        "phone_formatted": "(562) 686-2709",
                        "contact_name": "Elon Musk",
                        "avatar_url": "https://api.yappy.im/api/avatar/YAPPY",
                        "identifier": "BF4DF979-86E9-830D-BFC3-7G9F084D237B"
                    }
                ],
            "last_message": 1448165156010,
            "unread_SMS_count" : 2,
            "unread_Yappy_count" : 0,
            "has_Yappy" : true,
            "recipient_last_veiwed_yappy_message" : 1448165156010,
            "scheduled" = 1,
            "active": true,
            "created": 1448165156010,
            "modified": 1448165156010,
        }
    ]
}