# Conversations

Part of the [Ownbox SDK reference](https://www.ownbox.io/sdk/reference.md).

## m.messages

```python
m.messages(conversation, *, since=None)
```

A conversation's messages, oldest first.

Pass the last `at` you saw as `since` to get only what is new.

**Needs in machine.yaml:** `data: [conversations:read]`

**Returns:** `[{"id", "direction" ("in" or "out"), "sent_by", "body", "at"}]`.

Example (inside a job):

```python
for c in m.comments():
    convo = m.conversation_for(c)
    if convo:
        said = [x["body"] for x in m.messages(convo) if x["direction"] == "in"]
```

## m.comments

```python
m.comments(*, post=None, since=None)
```

Recent comments on the business's Instagram account.

Or on one `post`. `since` is an `at` a previous call returned, so a poll doesn't re-read everything. Replies under a comment and the account's own comments are left out. Pass one back, unchanged, to `m.reply_to_comment`. Never raises.

**Needs in machine.yaml:** `data: [conversations:read]`

**Returns:** `[{"id", "post", "account", "space", "text", "author": {"id", "username", "name"}, "at"}]`.

Example (inside a job):

```python
newest = m.comments(since=m.setting("comments_since"))
if newest:
    m.save_setting("comments_since", newest[-1]["at"])
```

## m.conversation_for

```python
m.conversation_for(comment)
```

The DM conversation with whoever wrote a comment.

It appears once they write back or tap a quick reply. Matched on their account, never a display name. Never raises.

**Needs in machine.yaml:** `data: [conversations:read]`

**Returns:** The conversation's id, or None until there is one.

Example (inside a job):

```python
convos = [m.conversation_for(c) for c in m.comments()]
```

## m.follows_you

```python
m.follows_you(conversation)
```

Does the person on a conversation follow the account?

None when Instagram didn't say, which is common: decide what None means for your machine.

**Needs in machine.yaml:** `data: [conversations:read]`

**Returns:** True, False or None.

Example (inside a job):

```python
for c in m.comments():
    convo = m.conversation_for(c)
    if convo and m.follows_you(convo) is False:
        m.save_setting("ask_to_follow", convo)
```

## m.claim

```python
m.claim(conversation, *, title, days=7, trigger=None)
```

Take charge of a conversation in the inbox.

While the machine holds it, the inbox doesn't draft it, greet it or count it as waiting on a person, and shows it as handled by `title`. It is never taken from another machine. Calling again renews it, and it lets go by itself after `days` (at most 30). Once a person on the team replied and took it over, no machine claims it again.

**Needs in machine.yaml:** `data: [conversations:write]`

**Returns:** True if this machine holds it.

Example (inside a job):

```python
for c in m.comments():
    convo = m.conversation_for(c)
    if convo and m.claim(convo, title="Quote Follow Up", days=7):
        m.release(convo, note="Asked about a quote; a person should answer.")
```

## m.release

```python
m.release(conversation, *, note='')
```

Let go of a conversation.

With a `note`, it is handed back to the team, and the note is shown to whoever answers it. Without one, the machine simply finished.

**Needs in machine.yaml:** `data: [conversations:write]`

**Returns:** True or False.

Example (inside a job):

```python
for c in m.comments():
    convo = m.conversation_for(c)
    if convo:
        m.release(convo)
```