TYPE: API Blueprint TITLE: REST API Reference (V1) UPDATED: 2021-12-22 FORMAT: 1A HOST: https://api.acme.com/v1 # Reference The Acme REST API offers access and control over all Acme data. All resources that you will most likely use are prefixed with a star symbol (⭐). **While integrating the REST API, you may be interested in the following guides:** + Navigation | Quickstart: Get started in minutes. -> /guides/hello-world/quickstart/ # Group Team Manages Acme teams. ## Base [/team] Manages teams. ### Check If Team Exists [HEAD /team{?domain}] Checks if given team exists (by domain). + Parameters + domain (string, required) - The team domain to check against + Request Check If Team Exists (application/json) + Tiers: `user` `app` + Body + Response 200 (application/json) + Response 404 (application/json) ### Create Team [POST /team] Creates a new team. + Attributes + name (string, required) - Team name + domain (string, required) - Team domain + Request Create Team (application/json) + Tiers: `user` + Body ``` { "name": "Acme, Inc.", "domain": "acme-inc.com" } ``` + Response 201 (application/json) + Body ``` { "error": false, "reason": "added", "data": { "team_id": "e2efddb0-d1ce-47fd-99f5-d3a5b69f1def" } } ``` + Response 423 (application/json) + Body ``` { "error": true, "reason": "quota_limit_exceeded", "data": {} } ``` ### Get A Team [GET /team/{team_id}] Resolves an existing team information. + Attributes + error (boolean) + reason (string) + data (object) + team_id (string) - Team identifier + name (string) - Team name + domain (string) - Team domain + Parameters + team_id (string) - The team identifier + Request Get Team Information (application/json) + Tiers: `user` `app` + Body + Response 200 (application/json) + Body ``` { "error": false, "reason": "resolved", "data": { "team_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc", "name": "Acme", "domain": "acme.com" } } ``` + Response 403 (application/json) + Body ``` { "error": true, "reason": "not_allowed", "data": {} } ``` + Response 404 (application/json) + Body ``` { "error": true, "reason": "not_subscribed", "data": {} } ``` ### Delete A Team [DELETE /team/{team_id}] Deletes an existing team. + Attributes + verify (string, required) - User password (used to double-authenticate deletion) + Parameters + team_id (string) - The team identifier + Request Delete A Team (application/json) + Tiers: `user` + Body ``` { "verify": "MySuperSecurePassword" } ``` + Response 200 (application/json) + Body ``` { "error": false, "reason": "deleted", "data": {} } ``` + Response 403 (application/json) + Body ``` { "error": true, "reason": "not_allowed", "data": {} } ``` + Response 404 (application/json) + Body ``` { "error": true, "reason": "team_not_found", "data": {} } ``` + Response 423 (application/json) + Body ``` { "error": true, "reason": "password_unverified", "data": {} } ``` ## Conversations [/team/{team_id}/conversations] Manages multiple team conversations. ### ⭐ List Conversations [GET /team/{team_id}/conversations/{page_number}{?search_query}{&search_type}{&search_operator}] Lists conversations for team. + Attributes + error (boolean) + reason (string) + data (array) + (object) + session_id (string) - Session identifier + team_id (string) - Team identifier + people_id (string) - People identifier + state (enum[string]) - Conversation state + Members + `pending` + `unresolved` + `resolved` + status (enum[number]) - Conversation status (an alias of state; useful for sorting conversations) + Members + `0` - Numeric code for pending status + `1` - Numeric code for unresolved status + `2` - Numeric code for resolved status + is_verified (boolean) - Whether session is verified or not (user email ownership is authenticated) + is_blocked (boolean) - Whether session is blocked or not (block messages from visitor) + availability (enum[string]) - Visitor availability + Members + `online` + `offline` + active (object) - User activity statistics + now (boolean) - Whether user is considered active right now or not + last (number) - Timestamp at which the user was last active + last_message (string) - Last message excerpt + participants (array) - External participants for this conversation + (object) + type (enum[string]) - External participant type + Members + `email` + target (string) - External participant target (ie. email address, identifier, etc.) + mentions (array[string]) - Mentioned user identifiers (from conversation messages) + created_at (number) - Conversation creation timestamp + updated_at (number) - Conversation update timestamp + compose (object) - Compose states + operator (object) - Compose state for operator + type (enum[string]) - Compose state type + Members + `start` + `stop` + excerpt (string) - Message excerpt for compose state + timestamp (number) - Timestamp for compose state + user (object) - Compose user information + user_id (string) - Compose user identifier + nickname (string) - Compose user nickname + avatar (string) - Compose user avatar + visitor (object) - Compose state for visitor + type (enum[string]) - Compose state type + Members + `start` + `stop` + excerpt (string) - Message excerpt for compose state + timestamp (number) - Timestamp for compose state + unread (object) - Unread messages counters + operator (number) - Unread messages counter for operator + visitor (number) - Unread messages counter for visitor + assigned (object) - Assigned operator (if any) + user_id (string) - Operator user identifier + meta (object) - Meta-data for conversation + nickname (string) - Visitor nickname + email (string) - Visitor email + phone (string) - Visitor phone + address (string) - Visitor address + ip (string) - Visitor IP address + data (object) - Visitor data + avatar (string) - Visitor avatar + device (object) - Device information + capabilities (array) - Visitor device capabilities + (enum[string]) + Members + `browsing` + `call` + geolocation (object) - Geolocation information for visitor device + country (string) - Country code + region (string) - Region code + city (string) - City name + coordinates (object) - Location coordinates + latitude (number) - Latitude coordinate + longitude (number) - Longitude coordinate + system (object) - Visitor device system information + os (object) - Operating system information + version (string) - OS version + name (string) - OS name + engine (object) - Rendering engine information + version (string) - Engine version + name (string) - Engine name + browser (object) - Browser information + major (string) - Browser major version (eg: version 8.1 has a major of 8) + version (string) - Browser version + name (string) - Browser name + useragent (string) - Visitor user agent + timezone (number) - Visitor device timezone offset (UTC) + locales (array[string]) - Visitor device locales + segments (array[string]) - Segments attributed to conversation + Parameters + team_id (string) - The team identifier + page_number (number, optional) - Page number for conversations paging + search_query (string, optional) - Search query in all conversations (text if type is `text` or `segment`, filter if type is `filter`) + search_type (string, optional) - Search type (either `text`, `segment` or `filter`) + search_operator (string, optional) - Search operator if search type is `filter` (`or` or `and` respectful to boolean algebra, defaults to `and` if not set) + Request List Conversations (application/json) + Tiers: `user` `app` + Scopes: `team:conversation:sessions` + Body + Response 206 (application/json) + Body ``` { "error": false, "reason": "listed", "data": [ { "session_id": "session_aaea8e1d-d6e3-4238-9252-d8c2e5579f5c", "team_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc", "people_id": "0cb89450-34fb-4d51-8905-040c1d14a594", "status": 1, "state": "unresolved", "is_verified": false, "is_blocked": false, "availability": "offline", "active": { "now": false }, "last_message": "All right, thanks.", "mentions": [], "participants": [ { "type": "email", "target": "jane.doe@acme-inc.com" } ], "updated_at": 1468401603070, "created_at": 1468341857826, "unread": { "operator": 0, "visitor": 1 }, "assigned": { "user_id": "a4c32c68-be91-4e29-8a05-976e93abbe3f" }, "meta": { "nickname": "Dan Boy", "email": "dan.boy@acme-inc.com", "ip": "104.236.186.68", "avatar": null, "device": { "capabilities": [ "call" ], "geolocation": { "country": "US", "region": "CA", "city": "San Francisco", "coordinates": { "latitude": 37.7749, "longitude": -122.4194 } }, "system": { "os": { "version": "10.11.5", "name": "Mac OS" }, "engine": { "name": "WebKit", "version": "537.36" }, "browser": { "major": "51", "version": "51.0.2683.0", "name": "Chrome" }, "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2683.0 Safari/537.36" }, "timezone": -120, "locales": [ "en", "fr" ] }, "segments": [ "customer", "friend" ] } } ] } ``` + Response 400 (application/json) + Body ``` { "error": true, "reason": "search_query_too_long", "data": {} } ``` + Response 402 (application/json) + Body ``` { "error": true, "reason": "subscription_upgrade_required", "data": {} } ``` + Response 403 (application/json) + Body ``` { "error": true, "reason": "not_allowed", "data": {} } ``` + Response 404 (application/json) + Body ``` { "error": true, "reason": "not_subscribed", "data": {} } ``` + Response 423 (application/json) + Body ``` { "error": true, "reason": "quota_limit_exceeded", "data": {} } ```