Inbox Conversations

Overview

This resource represents Inbox Conversations - a thread within each Inbox Messages can be created.

Parameters

OAuth Scopes:

inbox_read

Name	Type	Read/Write	Description
account	Integer	Read	Account's ID related to Conversation
assignee (host)	Integer	Read	Assignee's ID related to Conversation (Host's ID who is responsible for handling this conversation)
source	Integer	Read	Source's ID related to Conversation
bookings	Array	Read	Bookings IDs related to Conversation
inquiries	Array	Read	Inquiries IDs related to Conversation
messages	Array	Read	Messages IDs related to Conversation
participants	Array	Read	Participants ID related to Conversation
created_by_id	Integer	Read	ID of the resource that created the Conversation (User or Application - this is a polymorphic association)
created_by_type	String	Read	Type of the resource that created the Conversation (User or Application - this is a polymorphic association)
id	Integer	Read	Conversation's id.
default_channel	String	Read	Conversation's default channel — the Channel its underlying integration was created for, used by API clients to know which channel to set on Inbox Messages they create in this Conversation so the messages are relayed to the originating platform. See the Inbox Messaging guide and the list of Channels in the enums section.
subject	String	Read	Conversation's subject (for email-based Conversations).
created_at	Time	Read	Conversation's create time.
updated_at	Time	Read	Conversation's update time.
closed_at	Time	Read	Time when Conversation was closed.
deadline_response_at	Time	Read	Conversation's deadline response time.
last_message_at	Time	Read	Conversation's last message time.
marked_as_spam_at	Time	Read	Time when Conversation was marked as spam.
read_at	Time	Read	Time when conversations was viewed

inbox_write

Name	Type	Read/Write	Description	Constraints
account	Integer	Read	Account's ID related to Conversation
assignee (host)	Integer	Read	Assignee's ID related to Conversation (Host's ID who is responsible for handling this conversation)
source	Integer	Read	Source's ID related to Conversation
bookings	Array	Read	Bookings IDs related to Conversation
inquiries	Array	Read	Inquiries IDs related to Conversation
messages	Array	Read	Messages IDs related to Conversation
participants	Array	Read	Participants ID related to Conversation
created_by_id	Integer	Read	ID of the resource that created the Conversation (User or Application - this is a polymorphic association)
created_by_type	String	Read	Type of the resource that created the Conversation (User or Application - this is a polymorphic association)
id	Integer	Read	Conversation's id.
default_channel	String	Read/Write	Conversation's default channel — the Channel its underlying integration was created for. See the Inbox Messaging guide and the list of Channels in the enums section.	Must be one of the Channels
subject	String	Read/Write (create-only)	Conversation's subject (for email-based Conversations).
closed	Boolean	Write	An attribute for marking Conversation as closed (and will assign closed_at timestamp)
source_id	Integer	Write (create-only)	Source id related to the Conversation.
assignee_id	Integer	Write	Assignee's ID related to Conversation (Host's ID who is responsible for handling this conversation)
marked_as_spam	Boolean	Write	An attribute for marking Conversation as spam (and will assign marked_as_spam_at timestamp)
created_at	Time	Read	Conversation's create time.
updated_at	Time	Read	Conversation's update time.
closed_at	Time	Read	Time when Conversation was closed.
deadline_response_at	Time	Read/Write (create-only)	Conversation's deadline response time.
last_message_at	Time	Read	Conversation's last message time.
marked_as_spam_at	Time	Read	Time when Conversation was marked as spam.
read_at	Time	Read	Time when conversations was viewed

List Conversations

GET /inbox/conversations

OAuth Scopes:

inbox_read / inbox_write

response.json

{
  "links": {
    "conversations.account": "https://www.bookingsync.com/api/v3/accounts/{conversations.account}",
    "conversations.assignee": "https://www.bookingsync.com/api/v3/hosts/{conversations.assignee}",
    "conversations.source": "https://www.bookingsync.com/api/v3/sources/{conversations.source}",
    "conversations.bookings": "https://www.bookingsync.com/api/v3/bookings/{conversations.bookings}",
    "conversations.inquiries": "https://www.bookingsync.com/api/v3/inquiries/{conversations.inquiries}",
    "conversations.messages": "https://www.bookingsync.com/api/v3/inbox/messages/{conversations.messages}",
    "conversations.participants": "https://www.bookingsync.com/api/v3/inbox/participants/{conversations.participants}"
  },
  "conversations": [
    {
      "links": {
        "account": 1,
        "assignee": null,
        "bookings": [],
        "inquiries": [],
        "source": null,
        "messages": [],
        "participants": []
      },
      "closed_at": null,
      "created_at": "2018-12-20T14:25:57Z",
      "deadline_response_at": null,
      "default_channel": null,
      "id": 5,
      "last_message_at": "2018-11-22T12:19:57Z",
      "marked_as_spam_at": null,
      "subject": "Here goes subject of conversation.",
      "updated_at": "2018-12-20T14:25:57Z",
      "read_at": "2018-12-22T14:25:57Z"
    }
  ],
  "meta": {}
}

Get a single Conversation

Returns a single conversation identified by ID.

GET /inbox/conversations/:conversation_id

OAuth Scopes:

inbox_read / inbox_write

response.json

{
  "links": {
    "conversations.account": "https://www.bookingsync.com/api/v3/accounts/{conversations.account}",
    "conversations.assignee": "https://www.bookingsync.com/api/v3/hosts/{conversations.assignee}",
    "conversations.source": "https://www.bookingsync.com/api/v3/sources/{conversations.source}",
    "conversations.bookings": "https://www.bookingsync.com/api/v3/bookings/{conversations.bookings}",
    "conversations.inquiries": "https://www.bookingsync.com/api/v3/inquiries/{conversations.inquiries}",
    "conversations.messages": "https://www.bookingsync.com/api/v3/inbox/messages/{conversations.messages}",
    "conversations.participants": "https://www.bookingsync.com/api/v3/inbox/participants/{conversations.participants}"
  },
  "conversations": [
    {
      "links": {
        "account": 1,
        "assignee": null,
        "bookings": [],
        "inquiries": [],
        "source": null,
        "messages": [],
        "participants": []
      },
      "closed_at": null,
      "created_at": "2018-12-20T14:25:57Z",
      "deadline_response_at": null,
      "default_channel": null,
      "id": 5,
      "last_message_at": "2018-11-22T12:19:57Z",
      "marked_as_spam_at": null,
      "subject": "Here goes subject of conversation.",
      "updated_at": "2018-12-20T14:25:57Z",
      "read_at": "2018-12-22T14:25:57Z"
    }
  ],
  "meta": {}
}

Create a new Conversation

Creates a Conversation.

POST /inbox/conversations

OAuth Scopes:

inbox_write

request.json

{
  "conversations": [
    {
      "subject": "Subject.",
      "default_channel": "channelname",
      "last_message_at": "2018-12-20T14:25:57Z"
    }
  ]
}

response.json

{
  "links": {
    "conversations.account": "https://www.bookingsync.com/api/v3/accounts/{conversations.account}",
    "conversations.assignee": "https://www.bookingsync.com/api/v3/hosts/{conversations.assignee}",
    "conversations.source": "https://www.bookingsync.com/api/v3/sources/{conversations.source}",
    "conversations.bookings": "https://www.bookingsync.com/api/v3/bookings/{conversations.bookings}",
    "conversations.inquiries": "https://www.bookingsync.com/api/v3/inquiries/{conversations.inquiries}",
    "conversations.messages": "https://www.bookingsync.com/api/v3/inbox/messages/{conversations.messages}",
    "conversations.participants": "https://www.bookingsync.com/api/v3/inbox/participants/{conversations.participants}"
  },
  "conversations": [
    {
      "links": {
        "account": 1,
        "assignee": null,
        "bookings": [],
        "inquiries": [],
        "source": null,
        "messages": [],
        "participants": []
      },
      "closed_at": null,
      "created_at": "2018-12-20T14:25:57Z",
      "deadline_response_at": null,
      "default_channel": "channelname",
      "id": 5,
      "last_message_at": "2018-12-20T14:25:57Z",
      "marked_as_spam_at": null,
      "subject": "Subject.",
      "updated_at": "2018-12-20T14:25:57Z",
      "read_at": "2018-12-22T14:25:57Z"
    }
  ],
  "meta": {}
}

Update a Conversation

Returns an updated conversation identified by ID.

PUT /inbox/conversations/:conversation_id

Restrictions on updatable parameters

Only :assignee_id, :closed, :default_channel, :marked_as_spam attributes are allowed.

OAuth Scopes:

inbox_write

request.json

{
  "conversations": [
    {
      "default_channel": "channelname"
    }
  ]
}

response.json

{
  "links": {
    "conversations.account": "https://www.bookingsync.com/api/v3/accounts/{conversations.account}",
    "conversations.assignee": "https://www.bookingsync.com/api/v3/hosts/{conversations.assignee}",
    "conversations.source": "https://www.bookingsync.com/api/v3/sources/{conversations.source}",
    "conversations.bookings": "https://www.bookingsync.com/api/v3/bookings/{conversations.bookings}",
    "conversations.inquiries": "https://www.bookingsync.com/api/v3/inquiries/{conversations.inquiries}",
    "conversations.messages": "https://www.bookingsync.com/api/v3/inbox/messages/{conversations.messages}",
    "conversations.participants": "https://www.bookingsync.com/api/v3/inbox/participants/{conversations.participants}"
  },
  "conversations": [
    {
      "links": {
        "account": 1,
        "assignee": null,
        "bookings": [],
        "inquiries": [],
        "source": null,
        "messages": [],
        "participants": []
      },
      "closed_at": null,
      "created_at": "2018-12-20T14:25:57Z",
      "deadline_response_at": null,
      "default_channel": "channelname",
      "id": 5,
      "last_message_at": "2018-12-20T14:25:57Z",
      "marked_as_spam_at": null,
      "subject": "Subject.",
      "updated_at": "2018-12-20T14:25:57Z",
      "read_at": "2018-12-22T14:25:57Z"
    }
  ],
  "meta": {}
}

Add Bookings to a Conversation

Returns an updated conversation identified by ID.

PUT /inbox/conversations/:conversation_id/connect_booking

OAuth Scopes:

inbox_write

request.json

{
  "bookings": [
    {
      "id": 15
    }
  ]
}

response.json

{
  "links": {
    "conversations.account": "https://www.bookingsync.com/api/v3/accounts/{conversations.account}",
    "conversations.assignee": "https://www.bookingsync.com/api/v3/hosts/{conversations.assignee}",
    "conversations.source": "https://www.bookingsync.com/api/v3/sources/{conversations.source}",
    "conversations.bookings": "https://www.bookingsync.com/api/v3/bookings/{conversations.bookings}",
    "conversations.inquiries": "https://www.bookingsync.com/api/v3/inquiries/{conversations.inquiries}",
    "conversations.messages": "https://www.bookingsync.com/api/v3/inbox/messages/{conversations.messages}",
    "conversations.participants": "https://www.bookingsync.com/api/v3/inbox/participants/{conversations.participants}"
  },
  "conversations": [
    {
      "links": {
        "account": 1,
        "assignee": null,
        "bookings": [
          15
        ],
        "inquiries": [],
        "source": null,
        "messages": [],
        "participants": []
      },
      "closed_at": null,
      "created_at": "2018-12-20T14:25:57Z",
      "deadline_response_at": null,
      "default_channel": "channelname",
      "id": 5,
      "last_message_at": "2018-12-20T14:25:57Z",
      "marked_as_spam_at": null,
      "subject": "Subject.",
      "updated_at": "2018-12-20T14:25:57Z",
      "read_at": "2018-12-22T14:25:57Z"
    }
  ],
  "meta": {}
}

Remove Bookings from a Conversation

Returns an updated conversation identified by ID.

PUT /inbox/conversations/:conversation_id/disconnect_booking

OAuth Scopes:

inbox_write

request.json

{
  "bookings": [
    {
      "id": 15
    }
  ]
}

response.json

{
  "links": {
    "conversations.account": "https://www.bookingsync.com/api/v3/accounts/{conversations.account}",
    "conversations.assignee": "https://www.bookingsync.com/api/v3/hosts/{conversations.assignee}",
    "conversations.source": "https://www.bookingsync.com/api/v3/sources/{conversations.source}",
    "conversations.bookings": "https://www.bookingsync.com/api/v3/bookings/{conversations.bookings}",
    "conversations.inquiries": "https://www.bookingsync.com/api/v3/inquiries/{conversations.inquiries}",
    "conversations.messages": "https://www.bookingsync.com/api/v3/inbox/messages/{conversations.messages}",
    "conversations.participants": "https://www.bookingsync.com/api/v3/inbox/participants/{conversations.participants}"
  },
  "conversations": [
    {
      "links": {
        "account": 1,
        "assignee": null,
        "bookings": [],
        "inquiries": [],
        "source": null,
        "messages": [],
        "participants": []
      },
      "closed_at": null,
      "created_at": "2018-12-20T14:25:57Z",
      "deadline_response_at": null,
      "default_channel": "channelname",
      "id": 5,
      "last_message_at": "2018-12-20T14:25:57Z",
      "marked_as_spam_at": null,
      "subject": "Subject.",
      "updated_at": "2018-12-20T14:25:57Z",
      "read_at": "2018-12-22T14:25:57Z"
    }
  ],
  "meta": {}
}