Using the direct messaging API

Table of contents

• 1. Your inbox
• 2. Threads
• 3. Sending direct items
  • 3.1 Messages
  • 3.2 Link
  • 3.3 Profile
  • 3.4 Media
  • 3.5 Photo
  • 3.6 Video

1. Your inbox (example)

Pagination is not yet implemented, see #116 for reference. The current implementation will return the (20) most recent threads.

Retrieving the inbox will give you useful information and metadata about your direct inbox, but the most useful data from this response is likely to be the threads - this is a list containing a thread(chat) with information about users in the thread, the last sent item in the chat and other metadata.

The ApiClient has an attribute called inbox. This points to a class called Inbox, which contains all information. The attribute will be initialized as None and can be filled by calling client.direct_update_inbox.

2. Threads (example)

You can get thread_id's associated with your account from your inbox: client.inbox.threads. This is a list containing a Thread object for all retrieved threads. With a thread_idyou can create aDirectThread` object, which can be used to retrieve the complete thread.

thread = instauto.api.actions.structs.direct.DirectThread(thread_id)
thread = client.get_thread(thread) # using thread_id from a thread in the inbox response
items = thread.json()['thread']['items']

Retrieving a thread will give you metadata about the chat, such as the users in the chat and several other settings. The thread also has an items attribute, this is a list of chat items (e.g. messages, photos, media shares). Each chat item is a JSON object containing item type, item content, item timestamp, among others.

3. Sending Direct Items

For all the following examples you will need a client and the following imports:

import instauto.api.actions.structs.direct as dr

When sending items you need to set either recipients or threads or both in the item object. Examples of both are used below.

recipients: takes the form of a 2D list, where each element of recipients is a list of user ids. For example, if the recipients argument is set to [[user1_id], [user2_id, user3_id]], the item would be sent to user1 individually, then to user2 and user3 together in one thread.

threads: is a normal list where each element is a thread_id - you can find thread ids from the inbox. For example, if the threads argument is set to [thread1id, thread2id], the item would be sent to thread1 and thread2 (separately).

3.1 Messages (example)

rec = "12345678" # user id of recipient
m = dr.Message("message text", recipients=[[rec]])
client.direct_send(m)

3.2 Link (example)

For the LinkShare item, the first parameter is the link text, followed by a list of link URLs. Every link that you want to be clickable should be present in both the text and the URL list.

thread = "12345678" 
ls = dr.LinkShare("test link https://google.com", ["https://google.com"], threads=[thread])
client.direct_send(ls)

3.3 Profile (example)

rec1 = "12345678" # user id of recipient 1
rec2 = "23456789" # user id of recipient 2
profile_id = "34567890" # user id of profile you are sharing
ps = dr.ProfileShare(profile_id, recipients=[[rec1], [rec2]])
client.direct_send(ps)

3.4 Media (example)

rec1 = "12345678" # user id of recipient 1
rec2 = "23456789" # user id of recipient 2
rec3 = "34567890" # user id of recipient 3
media_id = "1212121289898989343434" # id of media being shared
ms = dr.MediaShare(media_id, recipients=[[rec1], [rec2, rec3]])
client.direct_send(ms)

3.5 Photo (example)

To share a photo we first have to upload it:

from instauto.api.actions.post import PostFeed
post = PostFeed(path="test.jpg", caption="")
response = client._upload_image(ph, quality=70)
upload_id = response['upload_id']

Then we can share it using the upload_id:

rec = "12345678" # user id of recipient
thread = "23456789" # thread id to share to
upload_id = "1212121289898989343434" # id of media being shared
dp = dr.DirectPhoto(upload_id, recipients=[[rec]], threads=[thread])
client.direct_send(dp)

3.6 Video Share

The video sharing feature is unfinished.