openapi: 3.1.0 info: title: Textline API version: 1.3.0 description: >- The Textline REST API allows you to send and receive messages, update conversation statuses, and read and write to your address book. Last updated: **18 September 2026** contact: name: Textline url: 'https://www.textline.com' x-updated: '2026-09-18' servers: - url: 'https://application.textline.com' description: Production paths: /auth/sign_in.json: post: operationId: Access_Token summary: Access Token description: >- Retrieve an access token to authenticate future requests. Multi-factor authentication (MFA) is required for all users; include the MFA token in the request. Then send the token on later requests with header `X-TGP-ACCESS-TOKEN` (or parameter `access_token`). You can also view your access token in Textline under Settings → Tools & Integrations → Developer API. requestBody: content: application/json: schema: type: object properties: user: type: object properties: email: type: string password: type: string required: - email - password api_key: type: string mfa_code: type: string examples: - user: email: chuck@mycompany.com password: mypassword api_key: 8a877f7d-b482-4ad0-9a71-be08c9ae1fb4 mfa_code: '654321' required: - api_key - mfa_code responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: mfa_verification_required: type: string email: type: string delivery_method: type: string alternate_methods: type: object properties: email: type: string sms: type: string examples: response: value: mfa_verification_required: 'true' email: chuck@mycompany.com delivery_method: app alternate_methods: email: 'true' sms: 'true' security: [] tags: - Authentication /api/conversations.json: get: operationId: List_Conversations summary: List Conversations description: >- Retrieve a paginated list of conversations. **Also: Retrieve a Conversation by Phone Number** — pass `phone_number` to return `{ conversation, posts }` for that contact instead of a list. Optional `after_uuid` / `before_uuid` page posts in that mode. parameters: - name: after_uuid in: query description: The uuid of a post to use as non inclusive lower bound of post results required: false schema: type: string example: '``' - name: before_uuid in: query description: The uuid of a post to use as non inclusive upper bound of post results required: false schema: type: string example: '``' - name: group_uuid in: query description: The uuid of the department from which you want to retrieve conversations required: false schema: type: string default: <1st Department UUID> example: '``' - name: page in: query description: 'Page of results (list mode) or page of posts (by phone). Default: 0.' required: false schema: type: number example: '0' - name: page_size in: query description: 'Number of results to return (max: 50). Default: 30.' required: false schema: type: number example: '30' - name: phone_number in: query description: 'If set, retrieve that contact''s conversation and posts instead of listing conversations.' required: false schema: type: string example: (222) 222-2222 responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string posts: type: array items: {} examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 posts: - attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user is_whisper: false marked_as_resolved: false transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 first_post: false message_type: SMS tags: - Conversations post: operationId: Message_a_Phone_Number summary: Message a Phone Number description: >- Send an outbound message to a phone number. A `comment` must be specified in the request. **Also supported on this endpoint:** - **Whisper a Phone Number** — use `whisper` / `whisper_attachments` instead of `comment` / `attachments`. - **Message a Group Conversation** — pass `phone_number` as an **array** plus required `group_uuid` for a group-messaging department. requestBody: required: true content: application/json: schema: type: object description: 'Shape depends on whether you are messaging, whispering, or using group messaging. See examples.' properties: phone_number: description: 'Contact phone number (string), or array of numbers for group messaging.' oneOf: - type: string example: (222) 222-2222 - type: array items: type: string example: - (222) 222-2222 - 786-876-5309 group_uuid: type: string description: Department UUID. Required for group messaging; optional otherwise (defaults to first department). comment: type: object description: Customer-visible message content (use for outbound SMS). properties: body: type: string whisper: type: object description: Agent-only whisper content. properties: body: type: string attachments: type: array description: Optional attachments for a customer-visible message. items: type: object properties: url: type: string whisper_attachments: type: array description: Optional attachments for a whisper. items: type: object properties: url: type: string resolve: type: string description: 'If set (e.g. "1"), resolve the conversation after sending.' examples: message_phone_number: summary: Message a phone number value: phone_number: (222) 222-2222 comment: body: hello world whisper_phone_number: summary: Whisper a phone number value: phone_number: (222) 222-2222 whisper: body: whisper group_messaging: summary: Message a group conversation value: phone_number: - (222) 222-2222 - 786-876-5309 - '+19497654321' group_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 comment: body: hello world responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string post: properties: attachments: type: array items: {} body: description: 'The body of the message, if there is one' type: - string - 'null' conversation_uuid: description: The uuid of the parent conversation type: string created_at: description: The unix time stamp of the created time for the post type: number creator: description: >- If the creator is a customer or user, additional fields specific to those types will be included type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} assigned_to: description: The agent that claimed the conversation with this post. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} uuid: type: string first_post: description: Is this the first post in the conversation/thread type: boolean message_type: description: 'Outlines whether the message is one of: SMS, webchat, null.' type: string type: object group: type: object properties: name: type: string phone_number: type: - string - 'null' uuid: type: string is_sms_group: type: boolean examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 post: assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user first_post: false is_whisper: false marked_as_resolved: false message_type: SMS transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true tags: - Conversations '/api/conversation/{uuid}.json': get: operationId: Retrieve_a_Conversation summary: Retrieve a Conversation description: Retrieve a single conversation and its posts parameters: - name: uuid in: path description: Identifier of the Conversation to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 - name: after_uuid in: query description: The uuid of a post to use as non inclusive lower bound of post results required: false schema: type: string example: '``' - name: before_uuid in: query description: The uuid of a post to use as non inclusive upper bound of post results required: false schema: type: string example: '``' - name: page in: query description: The page of posts you want to retrieve required: false schema: type: number example: '0' - name: page_size in: query description: | The number of posts to be returned (max: 50) + Default: 30 required: false schema: type: number example: '30' responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string posts: type: array items: {} examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 posts: - attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user is_whisper: false marked_as_resolved: false transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 first_post: false message_type: SMS tags: - Conversations post: operationId: Message_a_Conversation summary: Message a Conversation description: >- Send an outbound message to a conversation. A `comment` must be specified in the request. **Also: Whisper a Conversation** — send an internal whisper by providing `whisper` (and optional `whisper_attachments`) instead of `comment`. parameters: - name: uuid in: path description: Identifier of the Conversation to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 requestBody: required: true content: application/json: schema: type: object properties: comment: type: object description: Customer-visible message properties: body: type: string attachments: type: array items: type: object properties: url: type: string whisper: type: object description: Internal whisper properties: body: type: string whisper_attachments: type: array items: type: object properties: url: type: string resolve: type: string description: 'If set (e.g. "1"), resolve after sending a message.' examples: message: summary: Message a conversation value: comment: body: hello world whisper: summary: Whisper a conversation value: whisper: body: hello friend this is a whisper responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string whisper: type: object properties: attachments: type: array items: {} body: description: 'The body of the whisper, if there is one' type: - string - 'null' conversation_uuid: description: The uuid of the parent conversation type: string created_at: description: The unix time stamp of the created time for the post type: number creator: description: >- If the creator is a customer or user, additional fields specific to those types will be included type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} uuid: type: string group: type: object properties: name: type: string phone_number: type: - string - 'null' uuid: type: string is_sms_group: type: boolean examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 whisper: attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello friend this is a whisper conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user is_whisper: true marked_as_resolved: false transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true tags: - Conversations /api/new_customer_post.json: post: operationId: Import_a_Message_as_a_Customer summary: Import a Message as a Customer description: >- This endpoint allows you to import a post into Textline as if the Customer sent an SMS to your account. This is useful for initiating conversations using another tool, like web chat, and then continuing over SMS. requestBody: content: application/json: schema: type: object properties: phone_number: description: The phone number of the contact whose conversation you want to retrieve type: string group_uuid: description: The uuid of the department from which you want to retrieve conversations type: string default: <1st Department UUID> comment: description: The content visible to the customer type: object properties: body: type: string attachments: type: array examples: - phone_number: (222) 222-2222 group_uuid: '``' comment: body: hello world attachments: - Attachment_Upload_Payload required: - phone_number responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: post: properties: attachments: type: array items: {} body: description: 'The body of the message, if there is one' type: - string - 'null' conversation_uuid: description: The uuid of the parent conversation type: string created_at: description: The unix time stamp of the created time for the post type: number creator: description: >- If the creator is a customer or user, additional fields specific to those types will be included type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} assigned_to: description: The agent that claimed the conversation with this post. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} uuid: type: string first_post: description: Is this the first post in the conversation/thread type: boolean message_type: description: 'Outlines whether the message is one of: SMS, webchat, null.' type: string type: object group: type: object properties: name: type: string phone_number: type: - string - 'null' uuid: type: string is_sms_group: type: boolean examples: response: value: post: assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user first_post: false is_whisper: false marked_as_resolved: false message_type: SMS transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true tags: - Conversations '/api/conversation/{uuid}/resolve.json': post: operationId: Resolve_a_Conversation summary: Resolve a Conversation description: >- Change a conversation to the resolved state. You are also able to set a disposition when resolved (if on a pro plan and configured). parameters: - name: uuid in: path description: Identifier of the Conversation to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 requestBody: description: The identifier of the disposition you would like to use when resolving the conversation. content: application/json: schema: type: string responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string post: properties: attachments: type: array items: {} body: description: 'The body of the message, if there is one' type: - string - 'null' conversation_uuid: description: The uuid of the parent conversation type: string created_at: description: The unix time stamp of the created time for the post type: number creator: description: >- If the creator is a customer or user, additional fields specific to those types will be included type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} assigned_to: description: The agent that claimed the conversation with this post. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} uuid: type: string first_post: description: Is this the first post in the conversation/thread type: boolean message_type: description: 'Outlines whether the message is one of: SMS, webchat, null.' type: string type: object group: type: object properties: name: type: string phone_number: type: - string - 'null' uuid: type: string is_sms_group: type: boolean examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 post: assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user first_post: false is_whisper: false marked_as_resolved: false message_type: SMS transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true tags: - Conversations '/api/conversation/{uuid}/transfer.json': post: operationId: Transfer_a_Conversation summary: Transfer a Conversation description: >- Transfer a conversation to another agent using their user_uuid or email address (only one is required). The specified agent must belong to the same department as the conversation parameters: - name: uuid in: path description: Identifier of the Conversation to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 requestBody: content: application/json: schema: type: object properties: user_uuid: description: The uuid of the user you want the conversation transferred to type: string assignee: description: The email address of the user you want the conversation transferred to type: string examples: - user_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 assignee: sample@textline.com required: - user_uuid - assignee responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string post: properties: attachments: type: array items: {} body: description: 'The body of the message, if there is one' type: - string - 'null' conversation_uuid: description: The uuid of the parent conversation type: string created_at: description: The unix time stamp of the created time for the post type: number creator: description: >- If the creator is a customer or user, additional fields specific to those types will be included type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} assigned_to: description: The agent that claimed the conversation with this post. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} uuid: type: string first_post: description: Is this the first post in the conversation/thread type: boolean message_type: description: 'Outlines whether the message is one of: SMS, webchat, null.' type: string type: object group: type: object properties: name: type: string phone_number: type: - string - 'null' uuid: type: string is_sms_group: type: boolean examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 post: assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user first_post: false is_whisper: false marked_as_resolved: false message_type: SMS transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true tags: - Conversations '/api/conversation/{uuid}/schedule.json': post: operationId: Schedule_a_Message_to_a_Conversation summary: Schedule a Message to a Conversation description: Schedule an outbound message to a conversation. requestBody: content: application/json: schema: type: object properties: comment: description: The content visible to the customer type: object properties: body: type: string required: - body timestamp: description: 'The unix timestamp, in seconds, of the time you want the message to be sent.' type: number attachments: type: array examples: - comment: body: hello world timestamp: 1497308340 attachments: - Attachment_Upload_Payload required: - timestamp responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string post: properties: attachments: type: array items: {} body: description: 'The body of the message, if there is one' type: - string - 'null' conversation_uuid: description: The uuid of the parent conversation type: string created_at: description: The unix time stamp of the created time for the post type: number creator: description: >- If the creator is a customer or user, additional fields specific to those types will be included type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} assigned_to: description: The agent that claimed the conversation with this post. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} uuid: type: string first_post: description: Is this the first post in the conversation/thread type: boolean message_type: description: 'Outlines whether the message is one of: SMS, webchat, null.' type: string type: object group: type: object properties: name: type: string phone_number: type: - string - 'null' uuid: type: string is_sms_group: type: boolean examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 post: assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user first_post: false is_whisper: false marked_as_resolved: false message_type: SMS transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true tags: - Messaging Tools /api/conversations/schedule.json: post: operationId: Schedule_a_Message_to_a_Phone_Number summary: Schedule a Message to a Phone Number description: Schedule an outbound message given a phone number. requestBody: content: application/json: schema: type: object properties: timestamp: description: 'The unix timestamp, in seconds, of the time you want the message to be sent.' type: number phone_number: description: The phone number of the contact whose conversation you want to retrieve type: string group_uuid: description: The uuid of the department from which you want to retrieve conversations type: string default: <1st Department UUID> comment: description: The content visible to the customer type: object properties: body: type: string required: - body attachments: type: array examples: - timestamp: 1497308340 phone_number: (222) 222-2222 group_uuid: '``' comment: body: hello world attachments: - Attachment_Upload_Payload required: - timestamp - phone_number responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversation: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean resolved: type: boolean uuid: type: string post: properties: attachments: type: array items: {} body: description: 'The body of the message, if there is one' type: - string - 'null' conversation_uuid: description: The uuid of the parent conversation type: string created_at: description: The unix time stamp of the created time for the post type: number creator: description: >- If the creator is a customer or user, additional fields specific to those types will be included type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} assigned_to: description: The agent that claimed the conversation with this post. type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} uuid: type: string first_post: description: Is this the first post in the conversation/thread type: boolean message_type: description: 'Outlines whether the message is one of: SMS, webchat, null.' type: string type: object group: type: object properties: name: type: string phone_number: type: - string - 'null' uuid: type: string is_sms_group: type: boolean examples: response: value: conversation: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 post: assigned_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 attachments: - content_type: image/jpeg name: my_photo.png url: 'https://example.com/image.png' body: hello world conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: 1493923935 creator: name `Chuck Finley`: '' type: user first_post: false is_whisper: false marked_as_resolved: false message_type: SMS transferred_to: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true tags: - Messaging Tools /api/announcements.json: post: operationId: Send_an_Announcement summary: Send an Announcement description: >- Send an Announcement to a group of contacts. `selection_type` must be one of: `tags`, `saved-searches`, or `phone_numbers`. [Variables are supported](https://help.textline.com/en/articles/6660352). **Also supported on this endpoint:** - **Send an Announcement to Uploaded Contacts** — `selection_type: csv` with `recipients.csv_data` (base64 CSV). - **Schedule an Announcement** — set `scheduled: true` and `mass_text.timestamp` (unix seconds). requestBody: required: true content: application/json: schema: type: object required: - selection_type - recipients - mass_text properties: selection_type: type: string description: 'One of: tags, saved-searches, phone_numbers, csv' example: tags recipients: type: object description: Exactly one selection should be provided (except csv uses csv_data). properties: saved_search_uuid: type: string tag: type: string phone_numbers: type: array items: type: string csv_data: type: string description: Base64-encoded CSV for selection_type=csv mass_text: type: object required: - group_uuid - comment_body - title properties: group_uuid: type: string comment_body: type: string title: type: string resolve_on_send: type: string assignment_target_uuid: type: string reply_window_value: type: string reply_assignment_target_uuid: type: string timestamp: type: string description: Required when scheduling (unix timestamp in seconds). scheduled: type: boolean description: Set true when scheduling a future announcement. examples: send_by_tag: summary: Send announcement by tag value: selection_type: tags recipients: tag: VIP mass_text: group_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 comment_body: Test announcement title: Test send_csv: summary: Send announcement to uploaded CSV value: selection_type: csv recipients: csv_data: >- bmFtZSxwaG9uZSBudW1iZXIsY3VzdG9tX21lc3NhZ2UKdGV4dGxpbmUsNDE1ODQ5NDM0OSxob3cgdG8gZW5jb2RlIHlvdXIgQ1NW mass_text: group_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 comment_body: 'Hi {{upload.name}}, This is a test announcement about {{upload.custom_message}}' title: Test schedule: summary: Schedule an announcement value: selection_type: saved-searches recipients: saved_search_uuid: 44db893e-cf20-4279-96c7-60abb8a43b61 mass_text: group_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 comment_body: Test announcement title: Test timestamp: '1598991000' scheduled: true responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: authorized: type: string examples: response: value: authorized: 'true' tags: - Messaging Tools /api/dispositions.json: get: operationId: List_Dispositions summary: List Dispositions description: Retrieve a list of dispositions set up in the account parameters: [] responses: '200': description: OK headers: {} content: application/json: schema: type: array items: {} examples: response: value: - title: Technical Support uuid: ffb9ba22-1302-4045-8865-449d3eed461c group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true - name: Sales uuid: 2212a996-ec67-11ea-adc1-0242ac120002 tags: - Messaging Tools /api/surveys.json: get: operationId: List_Surveys summary: List Surveys description: 'Get a list of surveys, their type (NPS, CSAT, or Custom), and their UUID.' responses: '200': description: OK headers: {} content: application/json: schema: type: array items: {} examples: response: value: - name: Sample NPS type: NpsSurvey uuid: ffb9ba22-1302-4045-8865-449d3eed461c - name: Sample CSAT type: CsatSurvey uuid: 2212a996-ec67-11ea-adc1-0242ac120002 - name: Sample Custom type: CustomSurvey uuid: 28196e88-ec67-11ea-adc1-0242ac120002 tags: - Surveys '/api/survey/{uuid}/send.json': post: operationId: Send_a_Survey summary: Send a Survey description: 'Send a survey to a customer(s). The selection type must be one of: _tags, saved-searches,_ or _phone_numbers_ .' requestBody: content: application/json: schema: type: object properties: selection_type: description: 'must be one of: tags, saved-searches, or phone_numbers' type: string recipients: description: 'one of the below values is required, more than one selection will return an error.' type: object properties: saved_search_uuid: type: string tag: type: string phone_numbers: type: array target_group_uuid: description: >- Only for CAST surveys, this is the UUID for the department (group) you want to associate the survey with. type: string target_user_uuid: description: 'Only for CAST surveys, this is the UUID for the agent (user) you want to associate the survey with.' type: string examples: - selection_type: tags recipients: saved_search_uuid: 44db893e-cf20-4279-96c7-60abb8a43b61 tag: VIP phone_numbers: - '3058675309' - '4158675309' target_group_uuid: 6e4e0798-926d-4e10-92d4-252eb5e63ada target_user_uuid: 722a0019-3ff6-4028-b0c1-24d6e2f57d16 required: - selection_type - recipients responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: msg: description: X is the number of recipients you have selected type: string examples: response: value: msg: X survey queued for delivery tags: - Surveys '/api/survey/{uuid}/responses.json': get: operationId: List_Responses summary: List Responses description: >- Get a list of responses to a survey. By default it will return responses from the last 30 days. Date range can be adjusted in the request parameters. parameters: [] responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: responses: items: {} type: array examples: response: value: responses: - category: promoter customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true first_response_at: '1568298996' follow_up: '''Love it!''' invalid_rating_response: 'null' rating: '10' resolver: 'null' survey_sent_at: '2019-09-12T14:36:27.561Z' survey_type: this is a sample response for NPS surveys tags: - Great - Needs Review uuid: bf3474d8-ba85-456c-95d8-6d0c6e2a197b - customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true effort_rating: '5' effort_resolver: 'null' effort_uuid: 942fb2ca-ec77-11ea-adc1-0242ac120002 first_response_at: '1594676414' follow_up: 'Great service, keep it going!' invalid_effort_response: 'null' invalid_satisfaction_response: 'null' satisfaction_rating: '5' satisfaction_resolver: 'null' satisfaction_uuid: a548ca06-ec77-11ea-adc1-0242ac120002 survey_sent_at: '2020-07-13T21:40:04.975Z' survey_type: this is a sample response for CSAT surveys tags: [] target_group: name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true target_user: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 uuid: b5cd8e0c-ec77-11ea-adc1-0242ac120002 - customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true first_response_at: '1594676414' responses: - invalid_response: '``' prompt: question 1 text response: question 1 answer or response - invalid_response: '``' prompt: question 2 text response: question 2 answer or response survey_sent_at: '2020-07-13T21:40:04.975Z' survey_type: this is a sample response for custom surveys tags: [] uuid: b5cd8e0c-ec77-11ea-adc1-0242ac120002 tags: - Surveys x-s2o-warning: Operation List Responses has multiple requestBodies /api/customers.json: get: operationId: List_Customers summary: List Customers description: |- Retrieve a paginated list of customers. **Also: Retrieve a Customer by Phone Number** — pass `phone_number` to return that contact's details. parameters: - name: phone_number in: query description: 'If set, retrieve that contact instead of listing customers.' required: false schema: type: string example: (222) 222-2222 responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean examples: response: value: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true tags: - Customers post: operationId: Create_a_Customer summary: Create a Customer description: Create a new customer record in the address book requestBody: content: application/json: schema: type: object properties: customer: type: object properties: phone_number: type: string email: type: string name: type: string notes: type: string tags: description: >- A comma or space separated list of customer tags. Use underscores for tags that you want to space out. type: string required: - phone_number examples: - customer: phone_number: (222) 222-2222 email: chuck@mycompany.com name: Chuck Finley notes: some samples notes for the contact tags: foo_bar responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean examples: response: value: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true tags: - Customers '/api/customer/{uuid}.json': get: operationId: Retrieve_a_Customer summary: Retrieve a Customer description: Retrieve the details for a single customer parameters: - name: uuid in: path description: Identifier of the Customer to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean examples: response: value: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true tags: - Customers put: operationId: Update_a_Customer summary: Update a Customer description: >- Update a record in the address book. To include custom fields and their values, add the `custom_fields` object and use the custom field's uuid (found [here](#tag/Customers/operation/Retrieve_a_List_of_Custom_Fields)) and the value you want to set within the object. parameters: - name: uuid in: path description: Identifier of the Customer to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 requestBody: content: application/json: schema: type: object properties: customer: type: object properties: email: type: string name: type: string notes: type: string tags: description: >- A comma or space separated list of customer tags. Use underscores for tags that you want to space out. type: string tags_handling: description: >- A way to tell Textline how to process the values in Tags. Valid options are: add, remove, and replace. type: string archived: description: >- Remove the contact's messages from the conversation dashboard and prevent users from sending them Announcements and Surveys. You may search for the contact specifically to see their messages. type: boolean blocked: description: >- Prevent a contact's messages by being seen in the conversation dashboard. You may search for the contact specifically to see their messages. type: boolean unreachable: description: Should the customer be unsubscribed so that you do not message them at all. type: boolean custom_fields: type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: description: >- To update custom field for a customer, you must first get the custom field's UUID and use that to repace field_uuid type: string 342fbe5b-da20-4f82-b899-53f4a5b0a8df: type: string examples: - customer: email: chuck@mycompany.com name: Chuck Finley notes: some samples notes for the contact tags: foo_bar tags_handling: replace archived: false blocked: false unreachable: false custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: custom field 1 value 342fbe5b-da20-4f82-b899-53f4a5b0a8df: custom field 2 value responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: customer: type: object properties: avatar_url: type: - string - 'null' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' notes: type: - string - 'null' phone_number: type: - string - 'null' reachable_by_sms: description: Is this customer capable of receiving sms type: boolean tags: type: array items: {} uuid: type: string facebook_id: type: - string - 'null' custom_fields: description: >- This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string 116bad5a-6233-472d-bcf0-199d53342a82: type: string consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean verified: description: >- This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean examples: response: value: customer: avatar_url: 'https://example.com/image.png' blocked: false archived: false name: Chuck Finley notes: '``' phone_number: (222) 222-2222 reachable_by_sms: true tags: - foo - bar uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: 'null' custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true verified: true tags: - Customers /api/customers/request_consent.json: post: operationId: Request_Contact_Consent summary: Request Contact Consent description: >- For HIPAA and Pro accounts setup with Contact Consent, this endpoint can send a request to a Contact to collect consent to have conversations over text messages. A group UUID (department) is a required parameter along wtih one of the following: Contact UUID or phone number. requestBody: content: application/json: schema: type: object properties: group_uuid: description: >- The uuid of the department from which you want to retrieve conversations. Not using a department UUID will have the whisper go out on your first department. type: string customer_uuid: description: The phone number of the contact that you would like to send the Contact Request to. type: string phone_number: description: The phone number of the contact that you would like to send the Contact Request to. type: string examples: - group_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 customer_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 phone_number: '4148675309' required: - group_uuid responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: success: type: number examples: response: value: success: 1 tags: - Customers /api/customers/set_consent.json: post: operationId: Set_Contact_Consent summary: Set Contact Consent description: >- For HIPAA and Pro accounts setup with Contact Consent, this endpoint can set contact's consent status. To do this, your account must have [API import allowed](https://application.textline.com/organization/consent_settings) and the user making the API request must have the "Can manually set consent" permission on [for their role](https://application.textline.com/organization/agents/roles). You must then use the Contact's phone number or UUID (only 1 is needed in the body) and their consent status (true or false). requestBody: content: application/json: schema: type: object properties: customer_uuid: description: The phone number of the contact that you would like to send the Contact Request to. type: string phone_number: description: The phone number of the contact that you would like to send the Contact Request to. type: string consent: description: A true (1) or false (0) value to set the consent status of a contact. type: number examples: - customer_uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 phone_number: '4148675309' consent: 1 required: - consent responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: success: type: number examples: response: value: success: 1 tags: - Customers /api/address_book/custom_fields.json: get: operationId: Retrieve_a_List_of_Custom_Fields summary: Retrieve a List of Custom Fields description: >- Retrieve a list of custom Address Book fields currently setup in your organization. This returns the name, type, and UUID for the field. The UUID can then be used to update Customers' info other calls. responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: fields: type: array items: {} examples: response: value: fields: - data_type: string name: Custom Field 1 uuid: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0 - data_type: link name: Custom Field 2 uuid: 342fbe5b-da20-4f82-b899-53f4a5b0a8df tags: - Customers /api/address_book/saved_searches.json: get: operationId: Retrieve_a_list_of_Saved_Searches summary: Retrieve a list of Saved Searches description: >- Retrieve a list of Saved Searches and their parameters currently setup in your organization. This returns the name, description, and UUID for the Saved Search. The UUID can then be used as a recipient in other API calls. responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: saved_search: type: array items: {} examples: response: value: saved_search: - name: saved_search_1 description: saved_search_parameters uuid: 44db893e-cf20-4279-96c7-60abb8a43b61 - name: customers with tags description: has tags uuid: dd9d4cc2-c6df-421e-8925-09ec93461482 tags: - Customers /api/organization.json: get: operationId: Organization_Details summary: Organization Details description: Retrieve information about your organization parameters: - name: include_groups in: query description: 'If true, the response will include details about the departments in the organization' required: false schema: type: boolean default: '0' example: '0' - name: include_users in: query description: 'If true, the response will include details about the users/agents in the organization' required: false schema: type: boolean default: '0' example: '0' responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: organization: type: object properties: name: type: string groups: type: array items: {} users: type: array items: {} examples: response: value: organization: name: My Company groups: - name: Sales phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: true users: - avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 tags: - Account /api/groups.json: get: operationId: Department_Details summary: Department Details description: >- Retrieve information about the departments in your account. Similar to the organization call, except with more detail and without nesting. responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: departments: type: array items: {} examples: response: value: departments: - name: Customer Service uuid: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0 phone_number: (415) 849-4349 is_sms_group: true user_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 type: sms facebook_page_id: 'null' smart_sms_phone_numbers: - display_phone_number: (305) 867-5309 location: 'Miami, Florida, US' tags: - Account /api/users.json: get: operationId: Agent_Details summary: Agent Details description: >- Retrieve information about the agents in your account. Similar to the organization call, except with more detail and without nesting. parameters: [] responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: user: type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} examples: response: value: user: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 tags: - Account x-s2o-warning: Operation Agent Details has multiple requestBodies '/api/users/{uuid}/on_call.json': post: operationId: Turn_on_availability summary: Turn on availability description: Make the agent available in your account. Important for turning on notifications. parameters: - name: uuid in: path description: Identifier of the User to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: user: type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} examples: response: value: user: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 tags: - Account delete: operationId: Turn_off_availability summary: Turn off availability description: Make the agent unavailable in your account. Important for turning off notifications. parameters: - name: uuid in: path description: Identifier of the User to perform action with. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: user: type: object properties: avatar_url: type: - string - 'null' name: type: string on_call: description: Is this agent available to receive notifications type: boolean username: type: string uuid: type: string email: type: string permission_level: type: string group_uuids: type: array items: {} examples: response: value: user: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: false username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Admin group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 tags: - Account /api/reporting/conversations.json: get: operationId: List_Conversations summary: List Conversations description: >- This will list all conversations in the group (department). You can set other parameters to filter the response. By default, this call responds conversations associated with contacts that are archived and/or blocked. This is different from the other APIs, so make sure to adjust your parameters as desired. parameters: [] responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: conversations: type: array items: {} meta: type: object properties: next_page: type: string prev_page: type: string total_records: type: number page: type: number examples: response: value: conversations: - reachable: true resolved: true uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 customer: archived: true avatar_url: 'https://s3.amazonaws.com/textline_assets/textline-hq-customer-avatar.png' blocked: true facebook_id: 'null' instagram_id: 'null' name: Chuck Finley notes: One bad mama jama tags: - burned - Miami uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 phone_number: (786) 867-5309 reachable_by_sms: true custom_fields: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: 'null' consent_status: true created_at: 1595262394 updated_at: 1646186097 num_threads: 1 meta: next_page: >- https://application.textline.com/api/reporting/conversations.json?search_uuid=9d6857bd-ddbf-4409-8444-084a6da90977&page=1&page_size=10 prev_page: 'null' total_records: 1 page: 0 tags: - Reporting API x-s2o-warning: Operation List Conversations has multiple requestBodies '/api/reporting/conversation/{uuid}/posts.json': get: operationId: List_Posts_for_a_Conversation summary: List Posts for a Conversation description: >- This will list all posts for the specified conversation. You can set other parameters to filter the response. By default, this call responds conversations associated with contacts that are archived and/or blocked. This is different from the other APIs, so make sure to adjust your parameters as desired. parameters: - name: uuid in: path description: Identifier of the conversation of which to get the posts. required: true schema: type: string example: 84a2c56f-6b79-4764-811d-90880e2757b4 responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: posts: type: array items: {} meta: type: object properties: next_page: type: string prev_page: type: string total_records: type: number page: type: number examples: response: value: posts: - assigned_to: 'null' attachments: [] body: 'Hi Michael, Wrapping up here at work, get me a mojito.' created_at: 1644586642 is_whisper: 'false' marked_as_resolved: false uuid: 2829ffdf-282c-477a-bea0-3a9158126a8e transferred_to: 'null' creator: avatar_url: 'https://example.com/image.png' name: Chuck Finley on_call: true username: ChuckF uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com permission_level: Sidekick group_uuids: - 21ca50a9-a85d-49d1-9266-0df69fd5a9ef - 35c450e8-5b60-46e2-b691-481419462c16 type: user conversation_uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 thread_uuid: 1e5d3b35-0666-4fd5-b035-2f5af16fbf40 first_post: true first_response: true meta: next_page: >- https://application.textline.com/api/reporting/conversations.json?search_uuid=9d6857bd-ddbf-4409-8444-084a6da90977&page=1&page_size=10 prev_page: 'null' total_records: 1 page: 0 tags: - Reporting API x-s2o-warning: Operation List Posts for a Conversation has multiple requestBodies components: schemas: Authentication: {} Conversations: {} Resolve: {} Transfer: {} Announcements: {} Dispositions: {} Surveys: {} Customers: {} Customer: type: object properties: avatar_url: type: - string - 'null' examples: - 'https://example.com/image.png' blocked: description: Has this customer has been blocked from sending you messages type: boolean archived: description: Has this customer been archived in your address book type: boolean name: type: - string - 'null' examples: - Chuck Finley notes: type: - string - 'null' examples: - '``' phone_number: type: - string - 'null' examples: - (222) 222-2222 reachable_by_sms: description: Is this customer capable of receiving sms type: boolean examples: - true tags: type: array items: {} uuid: type: string examples: - deb79a6a-0652-4e14-86f2-dc8c5c502369 facebook_id: type: - string - 'null' examples: - 'null' custom_fields: description: This is a list of the custom fields created in the account by their uuid and the values for this contact. type: object properties: c43a1766-47e1-4c9c-a2cc-36bf424fcbc0: type: string examples: - Custom_Field_1_value 116bad5a-6233-472d-bcf0-199d53342a82: type: string examples: - 'null' consent_status: description: >- Has this customer given consent to be messaged. A feature of HIPAA and pro plan accounts. Values of true, false, and null, with null representing no request has been made. type: boolean examples: - true verified: description: This pertains to webchat and whether a contact has gone through the sync process for the conversation. type: boolean examples: - true Organization: {} Departments: {} Agents: {} Posts: {} Attachment: type: object properties: content_type: type: string examples: - image/jpeg name: type: string examples: - my_photo.png url: type: string examples: - 'https://example.com/image.png' Conversation: type: object properties: customer: $ref: '#/components/schemas/Customer' resolved: type: boolean examples: - true uuid: type: string examples: - 84a2c56f-6b79-4764-811d-90880e2757b4 Group: type: object properties: name: type: string examples: - Sales phone_number: type: - string - 'null' examples: - (222) 222-2222 uuid: type: string examples: - deb79a6a-0652-4e14-86f2-dc8c5c502369 is_sms_group: type: boolean examples: - true Post: type: object properties: attachments: type: array items: {} body: description: 'The body of the message, if there is one' type: - string - 'null' examples: - hello world conversation_uuid: description: The uuid of the parent conversation type: string examples: - 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: description: The unix time stamp of the created time for the post type: number examples: - 1493923935 creator: description: 'If the creator is a customer or user, additional fields specific to those types will be included' type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to. $ref: '#/components/schemas/User' assigned_to: description: The agent that claimed the conversation with this post. $ref: '#/components/schemas/User' uuid: type: string examples: - deb79a6a-0652-4e14-86f2-dc8c5c502369 first_post: description: Is this the first post in the conversation/thread type: boolean message_type: description: 'Outlines whether the message is one of: SMS, webchat, null.' type: string examples: - SMS Whisper: type: object properties: attachments: type: array items: {} body: description: 'The body of the whisper, if there is one' type: - string - 'null' examples: - hello friend this is a whisper conversation_uuid: description: The uuid of the parent conversation type: string examples: - 84a2c56f-6b79-4764-811d-90880e2757b4 created_at: description: The unix time stamp of the created time for the post type: number examples: - 1493923935 creator: description: 'If the creator is a customer or user, additional fields specific to those types will be included' type: object properties: name `Chuck Finley`: type: string type: type: string enum: - customer - system - user is_whisper: type: boolean examples: - true marked_as_resolved: description: Did this post mark the conversation as resolved type: boolean transferred_to: description: The agent that this post transferred the conversation to $ref: '#/components/schemas/User' uuid: type: string examples: - deb79a6a-0652-4e14-86f2-dc8c5c502369 User: type: object properties: avatar_url: type: - string - 'null' examples: - 'https://example.com/image.png' name: type: string examples: - Chuck Finley on_call: description: Is this agent available to receive notifications type: boolean examples: - true username: type: string examples: - ChuckF uuid: type: string examples: - deb79a6a-0652-4e14-86f2-dc8c5c502369 email: type: string examples: - chuckf@textline.com permission_level: type: string examples: - Admin group_uuids: type: array items: {} User_off: type: object properties: avatar_url: type: - string - 'null' examples: - 'https://example.com/image.png' name: type: string examples: - Chuck Finley on_call: description: Is this agent available to receive notifications type: boolean username: type: string examples: - ChuckF uuid: type: string examples: - deb79a6a-0652-4e14-86f2-dc8c5c502369 email: type: string examples: - chuckf@textline.com permission_level: type: string examples: - Admin group_uuids: type: array items: {} Content_Upload_Payload: type: object properties: comment: description: The content visible to the customer type: object properties: body: type: string examples: - hello world attachments: type: array items: {} resolve: description: A flag to denote whether the the conversation should be resolved after sending the message. type: string examples: - '1' Whisper_Upload_Payload: type: object properties: whisper: description: The content visible only to other agents type: object properties: body: type: string examples: - '`hello friend this is a whisper' whisper_attachments: type: array items: {} Attachment_Upload_Payload: type: object properties: url: type: string examples: - 'https://example.com/image.png' New_Post_Payload: type: object properties: conversation: $ref: '#/components/schemas/Conversation' post: $ref: '#/components/schemas/Post' group: $ref: '#/components/schemas/Group' New_Whisper_Payload: type: object properties: conversation: $ref: '#/components/schemas/Conversation' whisper: $ref: '#/components/schemas/Whisper' group: $ref: '#/components/schemas/Group' Specific_Conversations: {} Group_Conversations: {} Phone_Numbers: {} Importing_Messages: {} Schedule_Message_By_Conversation: {} Schedule_Message_By_Phone_Number: {} Send_Survey: {} Survey_Responses: {} Request_Contact_Consent: {} Set_Contact_Consent: {} Custom_Fields: {} Saved_Searches: {} Agent_Availability: {} tags: - name: Authentication description: |- Obtain an access token for subsequent API requests. See also the Authentication topic in the introduction for how to pass the token on later requests. - name: Conversations description: 'Send and receive messages, resolve, transfer, and import customer posts.' - name: Messaging Tools description: 'Schedule messages, send announcements, and list dispositions.' - name: Surveys description: 'List surveys, send surveys, and retrieve survey responses.' - name: Customers description: 'Address book: customers, consent, custom fields, and saved searches.' - name: Account description: 'Organization, departments (groups), agents, and agent availability.' - name: Webhooks description: >- Webhooks are user-configured HTTP callbacks that fire when an event occurs. Configure them in Textline at [Settings → Tools & Integrations → Developer API → New Webhook](https://application.textline.com/organization/new_webhook). More documentation: [support article](https://help.textline.com/en/articles/6660340). ### Signature validation Each webhook request includes: - `X-TGP-EVENT-SIGNATURE` — SHA256 signature - `X-TGP-EVENT-TYPE` — webhook type - `X-TGP-EVENT-TIME` — event time (unix seconds) The signature is `SHA256(webhook_type + event_time + webhook_secret)` (concatenated, in that order). The webhook secret is on the API settings page. - name: Reporting API description: >- Reporting APIs for historical / BI use. Responses include a `meta` object with `next_page`, `prev_page`, `total_records`, and `page`. Use the `next_page` / `prev_page` URLs for pagination (they do not include auth). Iterate conversations then posts per conversation, per department. webhooks: new_customer_post: post: tags: - Webhooks summary: New Customer Post description: |- Fires when a new inbound customer message (post) is created. Delivered with headers `X-TGP-EVENT-TYPE`, `X-TGP-EVENT-TIME`, and `X-TGP-EVENT-SIGNATURE`. operationId: New_Customer_Post requestBody: required: true content: application/json: schema: type: object properties: webhook: type: string webhook_uuid: type: string post: $ref: '#/components/schemas/Post' conversation: $ref: '#/components/schemas/Conversation' group: $ref: '#/components/schemas/Group' example: webhook: new_customer_post post: body: hello world uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 conversation: uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 resolved: false group: name: Sales uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 responses: '200': description: Return 200 to acknowledge receipt. new_outbound_post: post: tags: - Webhooks summary: New Outbound Post description: |- Fires when a new outbound agent message (post) is created. Delivered with headers `X-TGP-EVENT-TYPE`, `X-TGP-EVENT-TIME`, and `X-TGP-EVENT-SIGNATURE`. operationId: New_Outbound_Post requestBody: required: true content: application/json: schema: type: object properties: webhook: type: string webhook_uuid: type: string post: $ref: '#/components/schemas/Post' conversation: $ref: '#/components/schemas/Conversation' group: $ref: '#/components/schemas/Group' example: webhook: new_outbound_post post: body: hello world uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 conversation: uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 resolved: false group: name: Sales uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 responses: '200': description: Return 200 to acknowledge receipt. new_whisper: post: tags: - Webhooks summary: New Whisper description: |- Fires when a new internal whisper is created. Delivered with headers `X-TGP-EVENT-TYPE`, `X-TGP-EVENT-TIME`, and `X-TGP-EVENT-SIGNATURE`. operationId: New_Whisper requestBody: required: true content: application/json: schema: type: object properties: webhook: type: string webhook_uuid: type: string post: $ref: '#/components/schemas/Post' conversation: $ref: '#/components/schemas/Conversation' group: $ref: '#/components/schemas/Group' example: webhook: new_whisper post: body: internal note is_whisper: true uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 conversation: uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 resolved: false group: name: Sales uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 responses: '200': description: Return 200 to acknowledge receipt. conversation_status_change: post: tags: - Webhooks summary: Conversation Status Change description: >- Fires when a conversation status changes (for example, resolved / unresolved), including related post payload when applicable. Delivered with headers `X-TGP-EVENT-TYPE`, `X-TGP-EVENT-TIME`, and `X-TGP-EVENT-SIGNATURE`. operationId: Conversation_Status_Change requestBody: required: true content: application/json: schema: type: object properties: webhook: type: string webhook_uuid: type: string post: $ref: '#/components/schemas/Post' conversation: $ref: '#/components/schemas/Conversation' group: $ref: '#/components/schemas/Group' example: webhook: conversation_status_change post: marked_as_resolved: true uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 conversation: uuid: 84a2c56f-6b79-4764-811d-90880e2757b4 resolved: true group: name: Sales uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 responses: '200': description: Return 200 to acknowledge receipt. customer_updated: post: tags: - Webhooks summary: Customer Updated description: |- Fires when a customer / contact record is updated. Delivered with headers `X-TGP-EVENT-TYPE`, `X-TGP-EVENT-TIME`, and `X-TGP-EVENT-SIGNATURE`. operationId: Customer_Updated requestBody: required: true content: application/json: schema: type: object properties: webhook: type: string webhook_uuid: type: string customer: $ref: '#/components/schemas/Customer' example: webhook: customer_updated customer: name: Chuck Finley phone_number: (222) 222-2222 uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 responses: '200': description: Return 200 to acknowledge receipt. user_status_change: post: tags: - Webhooks summary: User Status Change description: |- Fires when an agent availability / status changes (for example, on-call). Delivered with headers `X-TGP-EVENT-TYPE`, `X-TGP-EVENT-TIME`, and `X-TGP-EVENT-SIGNATURE`. operationId: User_Status_Change requestBody: required: true content: application/json: schema: type: object properties: webhook: type: string webhook_uuid: type: string user: $ref: '#/components/schemas/User' example: webhook: user_status_change user: name: Chuck Finley on_call: true uuid: deb79a6a-0652-4e14-86f2-dc8c5c502369 email: chuckf@textline.com responses: '200': description: Return 200 to acknowledge receipt. x-tagGroups: - name: Reference tags: - Authentication - Conversations - Messaging Tools - Surveys - Customers - Account - Webhooks - Reporting API x-topics: - title: Base URL content: |- All URLs referenced in the documentation have the following base: `https://application.textline.com/` - title: Authentication content: >- All requests except for the authentication request require an **access token**. You can obtain an access token by making a request to the authentication endpoint (described below) using your **API key** (obtained [here](https://application.textline.com/organization/api_settings)) as well as the email and password of the agent you want represented by your API requests. You can then store the access token and pass it to all subsequent requests via the header `X-TGP-ACCESS-TOKEN` or as a GET or POST parameter `access_token`. You can also view your access token by logging into Textline and going to [Settings -> Tools & Integrations -> Developer API](https://application.textline.com/organization/api_settings). - title: Rate Limit content: >- The Textline API has a rate limit of 200 requests per minute. Requests beyond this number will receive a response with a 429 status code. - title: Error Handling content: |- If the parameters provided to a request are invalid, the response will have a status of 400 and include a json encoded body with the list of errors keyed to the field with the error. Example: `{"errors": {"name": ["Must be present"]}}` - title: Conversation Links content: >- If you would like to create a link directly to a specific conversation, have a look at [our support documentation here](https://help.textline.com/en/articles/6660333). You only need a contact's phone number to start, but can also use the Department UUID which can be found in the Organization Details API call. - title: Permissions content: >- Access and responses to API calls will be limited by the permissions the user has within Textline. For example, a user that cannot see departments other than the ones they are in will only see the ones they are in for the department, `/api/groups.json`, call. For full access, make sure to use an account that is given all permissions. - title: Pagination content: 'On calls that return pages of results, the first and default page if no parameter is set is `page=0`.' - title: Postman collection content: >- The API calls have been put into a [Postman collection here.](https://www.postman.com/textline/workspace/production-api-documentation/collection/10308115-9136e792-dab9-416b-9e69-6efed340accc)