openapi: 3.2.0
info:
title: hiver-api Inbox API
version: 1.0.0
servers:
- url: https://api2.hiverhq.com/v1
tags:
- name: Inbox
description: ''
paths:
/inboxes:
get:
tags:
- Inbox
summary: List all the inboxes
description: List all the inboxes
operationId: Inbox_inbox/list-all-the-inboxes
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {token}
description: ''
default: ''
description: ''
example: Bearer {token}
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: ''
example:
results:
- id: '101'
display_name: Customer Support
channel_type: email
email: info@example.com
inbox_type: user
is_authorised: false
source_user:
id: '12323'
email: source@example.com
created_at: 1709036168
updated_at: 1709036168
pagination:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
results:
type: array
description: ''
example:
- id: '101'
display_name: Customer Support
channel_type: email
email: info@example.com
inbox_type: user
is_authorised: false
source_user:
id: '12323'
email: source@example.com
created_at: 1709036168
updated_at: 1709036168
items:
type: object
properties:
id:
type: string
description: ''
example: '101'
display_name:
type: string
description: ''
example: Customer Support
channel_type:
type: string
description: ''
example: email
email:
type: string
description: ''
example: info@example.com
inbox_type:
type: string
description: ''
example: user
is_authorised:
type: boolean
description: ''
example: false
source_user:
type: object
description: ''
example:
id: '12323'
email: source@example.com
properties:
id:
type: string
description: ''
example: '12323'
email:
type: string
description: ''
example: source@example.com
created_at:
type: number
description: ''
example: 1709036168
updated_at:
type: number
description: ''
example: 1709036168
pagination:
type: object
description: ''
example:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
next_page:
type: string
description: ''
example: Gygskjhgkjythjjhkgjhgsdf=
/inboxes/{inbox_id}:
get:
tags:
- Inbox
summary: Get an inbox by id
description: Get an Inbox by Id
operationId: Inbox_inbox/get-an-inbox-by-id
parameters:
- name: inbox_id
in: path
required: true
schema:
type: integer
example: ''
description: ID of the inbox to get details
default: ''
format: int64
description: ID of the inbox to get details
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {token}
description: ''
default: ''
description: ''
example: Bearer {token}
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: ''
example:
id: '101'
display_name: Customer Support
channel_type: email
email: info@example.com
inbox_type: user
is_authorised: false
source_user:
id: '12323'
email: source@example.com
created_at: 1709036168
updated_at: 1709036168
properties:
id:
type: string
description: Id of the Inbox
example: '101'
display_name:
type: string
description: Name of the Inbox
example: Customer Support
channel_type:
type: string
description: Type of the channel
example: email
email:
type: string
description: Email address of the inbox
example: info@example.com
format: email
inbox_type:
type: string
description: Type of the authentication done for the inbox
example: user
format: string
is_authorised:
type: boolean
description: True if Hiver has access to user's mailbox, False otherwise. If false, the access could've been lost and need to reinstated.
example: false
source_user:
type: object
description: The user from whom the inbound emails are added.
example:
id: '12323'
email: source@example.com
properties:
id:
type: string
description: ''
example: '12323'
email:
type: string
description: ''
example: source@example.com
created_at:
type: integer
description: Creation timestamp
example: 1709036168
updated_at:
type: integer
description: Last update timestamp
example: 1709036168
/inboxes/{inbox_id}/users:
get:
tags:
- Inbox
summary: Get all users in the inbox
description: Get all users in the inbox
operationId: Inbox_inbox/get-all-users-in-the-inbox
parameters:
- name: inbox_id
in: path
required: true
schema:
type: string
example: '343'
description: ID of inbox to get the user list for
default: ''
description: ID of inbox to get the user list for
example: '343'
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {token}
description: ''
default: ''
description: ''
example: Bearer {token}
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: ''
example:
results:
- id: '456342'
first_name: Phoebe
last_name: Buffay
email: p.buffay@friends.com
phone_number: '+19876543444'
is_joined: false
pagination:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
results:
type: array
description: ''
example:
- id: '456342'
first_name: Phoebe
last_name: Buffay
email: p.buffay@friends.com
phone_number: '+19876543444'
is_joined: false
items:
type: object
properties:
id:
type: string
description: ''
example: '456342'
first_name:
type: string
description: ''
example: Phoebe
last_name:
type: string
description: ''
example: Buffay
email:
type: string
description: ''
example: p.buffay@friends.com
phone_number:
type: string
description: ''
example: '+19876543444'
is_joined:
type: boolean
description: ''
example: false
pagination:
type: object
description: ''
example:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
next_page:
type: string
description: ''
example: Gygskjhgkjythjjhkgjhgsdf=
/inboxes/{inbox_id}/users/search:
get:
tags:
- Inbox
summary: Search users in the inbox
description: Search users in the inbox
operationId: Inbox_inbox/search-users-in-the-inbox
parameters:
- name: inbox_id
in: path
required: true
schema:
type: string
example: '343'
description: ID of inbox to get the user list for
default: ''
description: ID of inbox to get the user list for
example: '343'
- name: email
in: query
required: true
schema:
type: string
example: bob@example.com
description: Email address to be searched for by exact match
default: ''
description: Email address to be searched for by exact match
example: bob@example.com
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {token}
description: ''
default: ''
description: ''
example: Bearer {token}
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: ''
example:
results:
- id: '456342'
first_name: Phoebe
last_name: Buffay
email: p.buffay@friends.com
phone_number: '+19876543444'
is_joined: false
pagination:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
results:
type: array
description: ''
example:
- id: '456342'
first_name: Phoebe
last_name: Buffay
email: p.buffay@friends.com
phone_number: '+19876543444'
is_joined: false
items:
type: object
properties:
id:
type: string
description: ''
example: '456342'
first_name:
type: string
description: ''
example: Phoebe
last_name:
type: string
description: ''
example: Buffay
email:
type: string
description: ''
example: p.buffay@friends.com
phone_number:
type: string
description: ''
example: '+19876543444'
is_joined:
type: boolean
description: ''
example: false
pagination:
type: object
description: ''
example:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
next_page:
type: string
description: ''
example: Gygskjhgkjythjjhkgjhgsdf=
/inboxes/{inbox_id}/tags:
get:
tags:
- Inbox
summary: Get tags in the inbox
description: Get tags in the inbox
operationId: Inbox_inbox/get-tags-in-the-inbox
parameters:
- name: inbox_id
in: path
required: true
schema:
type: string
example: '343'
description: ID of inbox to get the user list for
default: ''
description: ID of inbox to get the user list for
example: '343'
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {token}
description: ''
default: ''
description: ''
example: Bearer {token}
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: ''
example:
results:
- id: '56789'
name: Priority
color_code: '#ce93d8'
type: user
created_at: 1708945347
pagination:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
results:
type: array
description: ''
example:
- id: '56789'
name: Priority
color_code: '#ce93d8'
type: user
created_at: 1708945347
items:
type: object
properties:
id:
type: string
description: ''
example: '56789'
name:
type: string
description: ''
example: Priority
color_code:
type: string
description: ''
example: '#ce93d8'
type:
type: string
description: ''
example: user
created_at:
type: number
description: ''
example: 1708945347
pagination:
type: object
description: ''
example:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
next_page:
type: string
description: ''
example: Gygskjhgkjythjjhkgjhgsdf=
post:
tags:
- Inbox
summary: Create tag in the inbox
description: Create tag in the inbox
operationId: Inbox_inbox/create-tags-in-the-inbox
parameters:
- name: inbox_id
in: path
required: true
schema:
type: string
example: ''
description: ID of inbox to create the tag in it
default: ''
description: ID of inbox to create the tag in it
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {token}
description: ''
default: ''
description: ''
example: Bearer {token}
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: ''
example:
tag_id: 784268
name: Property 123
color_hexcode: '#64b5f6'
background_hexcode: '#f2f4f5'
smid: 284967
description: Sales pipeline conversations
properties:
tag_id:
type: number
description: ''
example: 784268
name:
type: string
description: ''
example: Property 123
color_hexcode:
type: string
description: ''
example: '#64b5f6'
background_hexcode:
type: string
description: ''
example: '#f2f4f5'
smid:
type: number
description: ''
example: 284967
description:
type: string
description: ''
example: Sales pipeline conversations
requestBody:
description: Request body
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: ''
example: Property 123
color_hexcode:
type: string
description: ''
example: '#64b5f6'
description:
type: string
description: ''
example: Sales pipeline conversations
required:
- name
/inboxes/{inbox_id}/tags/search:
get:
tags:
- Inbox
summary: Search tags in the inbox
description: Search tags in the inbox
operationId: Inbox_inbox/search-tags-in-the-inbox
parameters:
- name: inbox_id
in: path
required: true
schema:
type: string
example: '343'
description: ID of inbox to get the user list for
default: ''
description: ID of inbox to get the user list for
example: '343'
- name: name
in: query
required: true
schema:
type: string
example: Priority
description: Name of the tag to be searched for
default: ''
description: Name of the tag to be searched for
example: Priority
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {token}
description: ''
default: ''
description: ''
example: Bearer {token}
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: ''
example:
results:
- id: '56789'
name: Priority
color_code: '#ce93d8'
type: user
created_at: 1708945347
pagination:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
results:
type: array
description: ''
example:
- id: '56789'
name: Priority
color_code: '#ce93d8'
type: user
created_at: 1708945347
items:
type: object
properties:
id:
type: string
description: ''
example: '56789'
name:
type: string
description: ''
example: Priority
color_code:
type: string
description: ''
example: '#ce93d8'
type:
type: string
description: ''
example: user
created_at:
type: number
description: ''
example: 1708945347
pagination:
type: object
description: ''
example:
next_page: Gygskjhgkjythjjhkgjhgsdf=
properties:
next_page:
type: string
description: ''
example: Gygskjhgkjythjjhkgjhgsdf=
x-theneo-metadata:
menu:
- name: Inbox
description: "An Inbox is an entity that has conversations & users. Most common form of an Inbox is a shared mailbox ([https://hiverhq.com/shared-inbox](https://hiverhq.com/shared-inbox)) which manages emails. The APIs only manage the shared mailbox. We plan to add other type of inboxes in the APIs soon. It can have tags to help manage the conversations better.\n\nFollowing is an example of an Inbox object\n\n\n {\n \"id\": \"101\",\n \"display_name\": \"Customer Support\",\n \"channel_type\": \"email\",\n \"email\": \"info@hiver.com\",\n \"inbox_type\": \"user\",\n \"is_authorised\": false,\n \"source_user\": {\n \"id\": \"765676\",\n \"email\": \"info@hiver.com\"\n },\n \"created_at\": 176878888,\n \"updated_at\": 176878888\n }\n\n\nFollowing is an example of an Inbox User object\n\n\n {\n \"id\": \"456\",\n \"first_name\": \"Phoebe\",\n \"last_name\": \"Buffay\",\n \"email\": \"p.buffay@friends.com\",\n \"phone_number\": \"+19876543444\",\n \"is_joined\": false\n }\n\n\nFollowing is an example of an Inbox Tag object\n\n\n {\n \"id\": \"56789\",\n \"name\": \"Priority\",\n \"color_code\": \"#ce93d8\",\n \"type\": \"user\",\n \"created_at\": 1708945347\n }\n"
subSections:
- name: List all the inboxes
operationId: Inbox_inbox/list-all-the-inboxes
description: List all the inboxes
- name: Get an inbox by id
operationId: Inbox_inbox/get-an-inbox-by-id
description: Get an Inbox by Id
- name: Get all users in the inbox
operationId: Inbox_inbox/get-all-users-in-the-inbox
description: Get all users in the inbox
- name: Search users in the inbox
operationId: Inbox_inbox/search-users-in-the-inbox
description: Search users in the inbox
- name: Get tags in the inbox
operationId: Inbox_inbox/get-tags-in-the-inbox
description: Get tags in the inbox
- name: Search tags in the inbox
operationId: Inbox_inbox/search-tags-in-the-inbox
description: Search tags in the inbox
- name: Create tag in the inbox
operationId: Inbox_inbox/create-tags-in-the-inbox
description: Create tag in the inbox
- name: Conversations
description: "A conversation can be part of one or more inboxes. It can be assigned to a member of the inbox, have a status and tags associated with it.\n\nFollowing is an example of a Conversation object\n\n\n {\n \"id\": \"234232\",\n \"assignee\": {\n \"assignee_type\": \"user\",\n \"assignee_id\": \"1028399\"\n },\n \"status\": \"open\",\n \"tag_ids\": [\n \"1234322\", \"343434\"\n ]\n }\n"
subSections:
- name: Get conversations in the inbox
operationId: Conversations_conversations/get-conversations-in-the-inbox
description: 'Get conversations in the inbox
**Note:** The Gmail Thread IDs returned in the response are scoped to the **user authenticated with the shared mailbox email address (the source user)**. These IDs can be used directly in other Hiver APIs that require Gmail identifiers.'
- name: Get a conversation in the inbox
operationId: Conversations_conversations/get-a-conversation-in-the-inbox
description: "Get a conversation in the inbox\n\n**Note:**\n\n* The `conversation_id` field accepts either **Hiver conversation ID** or **Gmail thread ID**.\n \n* The Gmail Thread ID and Message IDs returned in the response are scoped to the **user authenticated with the shared mailbox email address (the source user)**. These IDs can be used directly in other Hiver APIs that require Gmail identifiers."
- name: Update conversation in the inbox
operationId: Conversations_conversations/update-conversation-in-the-inbox
description: 'Update conversation in the inbox
**Note**: The `conversation_id` field accepts either **Hiver conversation ID** or **Gmail thread ID.**'
- name: Create shared draft for conversation
operationId: Conversations_conversations/update-conversation-in-the-inbox-copy
description: 'Create a Shared Draft in an inbox conversation
**Note:** To create a Shared Draft, always use the Gmail Message ID returned for the **user authenticated with the shared mailbox email address (the source user).** Gmail IDs are user-specific and may not match across different users. If the source user''s Gmail Message ID (`**id**`) is unavailable, you can use the global SMTP Message ID found in `**payload.headers**` under the header name `**Message-ID**` (e.g. `****`) as a fallback. This ID is consistent across all users for the same email.'
- name: Create note on conversation
operationId: Conversations_conversations/create-note-on-conversation
description: 'Create a note on a conversation.
**Note:** For mentions, list the teammate''s email in `mentions` and write the same bare email in `content` where the mention should appear, it will be rendered as `@name`.'