{ "openapi": "3.0.0", "info": { "version": "2.0.0", "title": "Vida API", "description": "Vida API Documentation" }, "servers": [ { "url": "https://api.vida.dev", "description": "Vida Production", "variables": { "baseUrl": { "default": "api.vida.dev", "description": "Production API Root" } } } ], "paths": { "/api/v2/tokens": { "get": { "tags": [ "Authorization" ], "summary": "List tokens", "description": "List all your existing tokens.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "description": "Token", "type": "string", "example": "9fe4f9...." }, "description": { "description": "Friendly description of token", "type": "string", "example": "Main app" }, "type": { "description": "Token type", "type": "string", "example": "admin" }, "timestamp": { "description": "Timestamp when created", "type": "string", "example": "1678829072" }, "userId": { "description": "User Id that owns token", "type": "number", "example": 3 } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Authorization" ], "summary": "Create a token", "description": "Create a new token for your account", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token created successfully" }, "token": { "type": "object", "properties": { "token": { "description": "Token", "type": "string", "example": "9fe4f9...." }, "description": { "description": "Friendly description of token", "type": "string", "example": "Main app" }, "type": { "description": "Token type", "type": "string", "example": "admin" }, "timestamp": { "description": "Timestamp when created", "type": "string", "example": "167882907" }, "userId": { "description": "User Id that owns token", "type": "number", "example": 3 } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "description": "Permission for token. Only admin currently supported", "type": "string", "default": "admin" }, "description": { "description": "Friendly description for token", "type": "string", "example": "Main app" } } } } } } }, "delete": { "tags": [ "Authorization" ], "summary": "Delete a token", "description": "Delete a token from your account", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "description": "Token for deletion", "type": "string", "default": "9fe4f9...." } } } } } } } }, "/api/v2/sip/ipWhitelist": { "get": { "tags": [ "SIP" ], "summary": "List SIP IP Whitelist", "description": "List all your existing SIP IP whitelist entries.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "ip": { "description": "Whitelisted IP", "type": "string", "example": "192.168.1.1" } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "SIP" ], "summary": "Add IP to SIP IP Whitelist", "description": "Add a new IP address to your SIP IP whitelist.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "IP entry created successfully" }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "ip": { "description": "Whitelisted IP", "type": "string", "example": "192.168.1.1" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ip", "label" ], "properties": { "ip": { "description": "IP address to whitelist", "type": "string", "example": "192.168.1.1" }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" } } } } } } }, "delete": { "tags": [ "SIP" ], "summary": "Remove IP from SIP IP Whitelist", "description": "Remove an existing IP address from your SIP IP whitelist.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "IP entry deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "description": "IP address to remove", "type": "string", "example": "192.168.1.1" } } } } } } } }, "/api/v2/phoneNumber/assign": { "post": { "tags": [ "Phone Numbers" ], "summary": "Assign phone number to your account", "description": "Assign phone number to your account for use", "responses": { "200": { "description": "Successfully assigned phone number to account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Unable to assign phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number", "country" ], "properties": { "number": { "description": "Phone Number to assign to your account", "type": "string", "example": "+12145551234" }, "country": { "description": "Country for the phone number to assign", "type": "string", "example": "US" } } } } } } } }, "/api/v2/phoneNumber/search/local/locality": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by locality", "description": "Search for a phone number based on city, region, and country.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber", "code" ], "properties": { "city": { "description": "City you are searching for. If the particular city is unavailable, phone numbers from a 10 mile radius will be returned", "type": "string", "example": "Austin" }, "region": { "description": "Region for the search. If searching within the U.S., this will be the state", "type": "string", "example": "TX" }, "country": { "description": "Country for the search", "type": "string", "example": "US" } } } } } } } }, "/api/v2/phoneNumber/search/local/prefix": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by prefix", "description": "Search for a phone number based on prefix.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber", "code" ], "properties": { "prefix": { "description": "Prefix you are searching for", "type": "string", "example": "216" }, "country": { "description": "Country used for the search", "type": "string", "example": "US" }, "strict": { "description": "If strict search is to be used. If no results found, will other numbers in same general area.", "type": "boolean", "default": true } } } } } } } }, "/api/v2/phoneNumber/search/local/phrase": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by phrase", "description": "Search for a phone number based on phrase.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phrase", "country" ], "properties": { "phrase": { "description": "String to search for. This supports asterisk wildcards *", "type": "string", "example": "*bitcoin*" }, "country": { "description": "Country used for the search", "type": "string", "example": "US" }, "region": { "description": "Region for the search. If searching within the U.S., this will be the state", "type": "string", "example": "TX" }, "city": { "description": "City you are searching for. If the particular city is unavailable, phone numbers from a 10 mile radius will be returned", "type": "string", "example": "Austin" } } } } } } } }, "/api/v2/conversations": { "get": { "tags": [ "Messaging" ], "summary": "List Priority Inbox", "description": "Fetch rooms in priority inbox", "parameters": [ { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": true, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many rooms per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "unread", "in": "query", "description": "Only return unread rooms", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "totalRooms": { "type": "number", "example": 100 }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "roomId": { "description": "Room Id", "type": "string", "example": "3:15" }, "name": { "description": "Other users full name", "type": "string", "example": "John Doe" }, "id": { "description": "userId of other user", "type": "number", "example": 15 }, "image": { "description": "Link to other users image", "type": "string", "example": "https://somepublicURl" }, "vidaPhoneNumber": { "description": "Other user Vida Phone Number", "type": "string", "example": "+12165169995" }, "unregistered": { "description": "If the other user is registered on Vida platform or offnet", "type": "boolean", "example": false }, "unregisteredDisplayName": { "description": "Display name for unregistered user which is often their phone number or email", "type": "string", "example": "+15125551234" }, "destinationInboxType": { "description": "Indicator which inbox on the other user side the conversation is in", "type": "string", "example": "+15125551234" }, "lastMessage": { "description": "Last message text in the room", "type": "string", "example": "That was awesome, thanks!" }, "lastMessageTimestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1710510072 }, "chatAgentCampaignId": { "description": "Agent Id that handled the message", "type": "string", "example": "campa....." } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/junkConversations": { "get": { "tags": [ "Messaging" ], "summary": "List Junk Inbox", "description": "Fetch rooms in junk inbox", "parameters": [ { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": true, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many rooms per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "unread", "in": "query", "description": "Only return unread rooms", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "totalRooms": { "type": "number", "example": 100 }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "roomId": { "description": "Room Id", "type": "string", "example": "3:15" }, "name": { "description": "Other users full name", "type": "string", "example": "John Doe" }, "id": { "description": "userId of other user", "type": "number", "example": 15 }, "image": { "description": "Link to other users image", "type": "string", "example": "https://somepublicURl" }, "vidaPhoneNumber": { "description": "Other user Vida Phone Number", "type": "string", "example": "+12165169995" }, "unregistered": { "description": "If the other user is registered on Vida platform or offnet", "type": "boolean", "example": false }, "unregisteredDisplayName": { "description": "Display name for unregistered user which is often their phone number or email", "type": "string", "example": "+15125551234" }, "destinationInboxType": { "description": "Indicator which inbox on the other user side the conversation is in", "type": "string", "example": "+15125551234" }, "lastMessage": { "description": "Last message text in the room", "type": "string", "example": "That was awesome, thanks!" }, "lastMessageTimestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1710510072 }, "chatAgentCampaignId": { "description": "Agent Id that handled the message", "type": "string", "example": "campa....." } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/messages/recent": { "get": { "tags": [ "Messaging" ], "summary": "Fetch Recent Messages", "description": "Fetch recent messages across all inboxes.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "from": { "description": "From User Id", "type": "number", "example": 1234567890 }, "fromUser": { "description": "From User Name", "type": "string", "example": "user_test" }, "to": { "description": "To User Id", "type": "number", "example": 878589 }, "toUser": { "description": "To User Name", "type": "string", "example": "support2" }, "rate": { "description": "Rate associated with the message", "type": "number", "example": 0 }, "usdRate": { "description": "USD rate associated with the message", "type": "number", "example": 0 }, "timestamp": { "description": "Epoch of the last message's timestamp", "type": "number", "example": 1718463395 }, "date": { "description": "Friendly Date", "type": "string", "example": "2024-06-15T14:56:35.000Z" }, "message": { "description": "Message text", "type": "string", "example": "Hi there! Lyle is currently unavailable. Could you please let me know the nature of your call or message and any specific details you'd like me to pass on to him? Thanks!" }, "content-type": { "description": "Content type of the message", "type": "string", "example": "text/plain" }, "disposition-notification": { "description": "Disposition notification status", "type": "string", "example": null }, "roomId": { "description": "Room Id", "type": "string", "example": "1:878589" }, "status": { "description": "Status of the message", "type": "string", "example": "success" }, "attachments": { "description": "Array of media attachment URLs", "type": "array", "items": { "type": "object", "properties": { "content-type": { "type": "string", "example": "audio/mp3" }, "filename": { "type": "string", "example": "mp3" }, "content-url": { "type": "string", "example": "https://example.com/media/recording.mp3" }, "attachmentType": { "type": "string", "example": "call" } } } }, "isLive": { "description": "Whether the message is live", "type": "boolean", "example": false }, "aiAgent": { "description": "Whether an AI agent is involved", "type": "boolean", "example": true }, "aiReward": { "description": "AI reward status", "type": "string", "example": null }, "aiRewardUsd": { "description": "AI reward in USD", "type": "number", "example": null }, "aiLeadRating": { "description": "AI lead rating", "type": "number", "example": null }, "aiLeadRatingReason": { "description": "Reason for AI lead rating", "type": "string", "example": null }, "aiAgentOverride": { "description": "AI agent override status", "type": "string", "example": null }, "gift": { "description": "If this message included a monetary gift", "type": "boolean", "example": false }, "source": { "description": "Source medium for the message", "type": "string", "example": "email" }, "uuid": { "description": "Unique ID for message", "type": "string", "example": "a4977f49-80a6-41f0-9add-93a270cdd781" }, "campaignId": { "description": "Campaign ID associated with the message", "type": "string", "example": "campa25290ee54602fbcb545d033c1a15ba12" }, "fromNumber": { "description": "Phone number of the sender", "type": "string", "example": "+15125551234" }, "toNumber": { "description": "Phone number of the recipient", "type": "string", "example": "+15125559876" }, "notify": { "description": "Notification flag", "type": "boolean", "example": false }, "targetInbox": { "description": "Target inbox", "type": "string", "example": "inbox" }, "type": { "description": "Type of message", "type": "string", "example": "call" }, "duration": { "description": "Duration of the call", "type": "number", "example": 9 }, "direction": { "description": "Direction of the call", "type": "string", "example": "inbound" }, "missedCall": { "description": "Whether it was a missed call", "type": "boolean", "example": false }, "bypassAgent": { "description": "Whether the agent was bypassed", "type": "boolean", "example": false }, "cnamSpam": { "description": "Whether the call was marked as spam by CNAM", "type": "boolean", "example": false }, "selfCall": { "description": "Whether the call was self-initiated", "type": "boolean", "example": true }, "callingUserIsContact": { "description": "Whether the calling user is a contact", "type": "boolean", "example": false }, "agentOutcome": { "description": "Outcome from the agent", "type": "string", "example": null }, "summary": { "description": "Summary of the message", "type": "string", "example": null }, "callDialog": { "description": "Array of dialog entries with roles and contents", "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "example": "Hello! This is the answering assistant. How can I help you?" } } } }, "campaign": { "description": "Campaign status", "type": "boolean", "example": true }, "diversion": { "description": "Diversion status", "type": "string", "example": null }, "voicemailRecording": { "description": "Voicemail recording details", "type": "string", "example": null }, "eventType": { "description": "Type of event", "type": "string", "example": "inbound-call" }, "forcedCampaign": { "description": "Forced campaign flag", "type": "boolean", "example": true } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/messages/{roomId}": { "get": { "tags": [ "Messaging" ], "summary": "Fetch Room Messages", "description": "Fetch all messages for a particular room Id", "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Room Id to fetch messages for", "example": "3:15" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "message": { "description": "Message text", "type": "string", "example": "Hey there!" }, "from": { "description": "From User Id", "type": "number", "example": 15 }, "fromUser": { "description": "From User Name", "type": "string", "example": "Brandon" }, "to": { "description": "From User Id", "type": "number", "example": 35554545 }, "toUser": { "description": "To User Name", "type": "string", "example": "Jillian" }, "timestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1699633022 }, "date": { "description": "Friendly Date", "type": "string", "example": "2023-11-10T16:17:02.000Z" }, "roomId": { "description": "Room Id", "type": "string", "example": "15:35554545" }, "status": { "description": "If message was delivered. Status of success indicates delivered", "type": "string", "example": "success" }, "attachments": { "description": "Array of media attachment Urls.", "type": "string", "example": "[]" }, "gift": { "description": "If this message included a monetary gift", "type": "boolean", "example": false }, "drip": { "description": "If this message was a paid drip", "type": "boolean", "example": false }, "uuid": { "description": "Unique id for message", "type": "string", "example": "3b38f0af-7341-49fd-acce-1749c904e00d" }, "source": { "description": "Source medium for the message. Could have sourced from a vida client, sms, voice, email", "type": "string", "example": "sms" }, "roomInitiator": { "description": "User name who first initiated contact for the room", "type": "string", "example": "brandon" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/publish": { "post": { "tags": [ "Agents" ], "summary": "Publish an Agent", "description": "Publish your staging agent to your active default agent. ", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent camp931829b5857f published" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/revert": { "post": { "tags": [ "Agents" ], "summary": "Revert an Agent", "description": "Revert staging agent to current default active agent settings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent camp931829b5857f unpublished" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "List all your existing webhook destinations.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "type": { "description": "Webhook type", "type": "string", "example": "call" } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Add Webhook", "description": "Add a new webhook destination.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook created successfully" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "type": { "description": "Webhook type", "type": "string", "example": "conversation" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "label", "type" ], "properties": { "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "type": { "description": "Webhook type", "type": "string", "example": "conversation" } } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Remove Webhook", "description": "Remove an existing webhook destination.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "description": "Webhook URL to remove", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" } } } } } } } }, "/api/v2/context": { "get": { "tags": [ "Knowledge" ], "summary": "Fetch Context", "description": "Fetch additional information context stored for conversations with a particular person.", "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Phone number in E.164 format or VIDA username of the user" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "context": { "type": "string", "example": "Customer Name: John Doe, Car Model: Toyota Camry, Last Oil Change: 2023-05-15" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Knowledge" ], "summary": "Add Context", "description": "Injects additional information context your agent can use in conversations with a specific person.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Context added successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "context" ], "properties": { "target": { "description": "Phone number in E.164 format or VIDA username of the user", "type": "string", "example": "+1234567890 or john_doe" }, "context": { "description": "Context information to inject", "type": "string", "example": "Customer Name: John Doe, Car Model: Toyota Camry, Last Oil Change: 2023-05-15" } } } } } } } }, "/api/v2/agent": { "post": { "tags": [ "Agents" ], "summary": "Update Agent", "description": "Update an agent", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent created." }, "campaignId": { "type": "string", "example": "camp931829b5857f...." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "description" ], "properties": { "type": { "description": "Type for this agent", "type": "string", "enum": [ "chatAgent" ] }, "title": { "description": "Title for Agent", "type": "string", "example": "Call Screener" }, "description": { "description": "Some description", "type": "string", "example": "Description" }, "welcomeMessage": { "description": "Message users see when initially visiting a agent", "type": "string", "example": "This brought to you by Wolf Cola" }, "welcomeMedia": { "description": "Media (e.g. Video Links) users see when initially visiting a campaign attached object such as a room or chatAgent", "type": "string", "example": "https://link.to.your.video" }, "welcomeMessageRecording": { "description": "Audio file (mp3) that is played when someone dials into your campaign Phone Number. This file must be uploaded to your vida media", "type": "string", "example": "greeting.mp3" }, "links": { "description": "Array of any http links to reference for external knowledge for your agent", "type": "array", "items": { "type": "string" }, "example": [ "https://vida.io/faq" ] }, "actions": { "description": "Actions that your agent can take including instructions and settings", "type": "array", "items": { "type": "string" }, "example": [ "transfer" ] }, "agentVoice": { "description": "Agent voice model to use", "type": "string", "example": "en-US Female" }, "agentTtsEngine": { "description": "Text to speech engine for this agent", "type": "string", "enum": [ "google", "11labs" ], "default": "google" }, "agentLang": { "description": "Agent language to be used for voice and transcriptions", "type": "string", "enum": [ "en-US", "es-MX", "es-ES", "es-US" ], "default": "en-US" }, "postRewardMessage": { "description": "Message sent to the user after they have received a reward from a chatAgent or sponsored room", "type": "string", "example": "Thanks for watching to receive 10% off your next order, use promo code GIVEME10OFF" }, "postRewardMedia": { "description": "Media (e.g. Video Links) users see along with your post reward message", "type": "string", "example": "https://link.to.your.video" }, "postRewardQualifiedLeadMessage": { "description": "Message sent to the user after reward grant that has met the minimum quality lead score", "type": "string", "example": "Wow! This looks like a match made in heaven. Here is an additional 25% off if you sign up with us today!" }, "qualityLeadMinScore": { "description": "Minimum lead score to be considered a quality lead. Will move to priority inbox and trigger postRewardQualifiedLeadMessage if set", "type": "integer", "example": 5, "default": 6 }, "agentInstructions": { "description": "Agent instructions for user interaction. This is for chatAgents only", "type": "string", "example": "I want you to payout rewards for users that answer a few questions about this promotional video." } } } } } } } }, "/api/v2/agentEventRules/staging": { "get": { "tags": [ "Agents" ], "summary": "Fetch Staging Agent", "description": "Fetch your Staging agent configuration.", "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentEventRules/default": { "get": { "tags": [ "Agents" ], "summary": "Fetch Live Agent", "description": "Fetch your Live (default) agent configuration.", "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/checkAgentUrl": { "get": { "tags": [ "Agent URLs" ], "summary": "Check agent url availability", "description": "Check if an agent url is available for use", "parameters": [ { "name": "targetUsername", "in": "query", "description": "Target username", "required": true, "example": "brandon", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "description": "Desired slug name", "required": true, "example": "weloveVida", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "available": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentUrl": { "get": { "tags": [ "Agent URLs" ], "summary": "Fetch existing agent url", "description": "Check if existing agent url exists for a user or create new one", "parameters": [ { "name": "targetUsername", "in": "query", "description": "Target username", "required": true, "example": "brandon", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug retrieved/fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Agent URLs" ], "summary": "Create agent url", "description": "Create a new url for an agent and replace existing one if exists", "responses": { "200": { "description": "Referral Slug Created Successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetUsername", "slug" ], "properties": { "targetUsername": { "description": "Target Username you are creating a referral slug for", "type": "string", "example": "brandon" }, "slug": { "description": "Desired slug name", "type": "string", "example": "welovevida" } } } } } } } }, "/api/v2/agent/{agentId}": { "get": { "tags": [ "Agents" ], "summary": "Get Agent", "description": "Fetch an agent details", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id", "example": "campa931829b5857f...." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "sponsorship": { "properties": { "id": { "description": "Agent Id", "type": "string", "example": "campa931829b5857f...." } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/outboundCall": { "post": { "tags": [ "Agents" ], "summary": "Outbound Call from Agent", "description": "Use this endpoint to initiate an outbound call from your Vida agent to a destination number or user. Your agent will handle the call.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Outbound call initiated." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "context": { "description": "Additional context you want your Agent to be aware of when handling the call.", "type": "string", "example": "Name: Lyle Pratt. Interest: Completed a call back form on our website for more information about our products." }, "target": { "description": "Phone number in E.164 format or VIDA username of the user", "type": "string", "example": "+1234567890 or john_doe" } } } } } } } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "query", "name": "token", "description": "Vida API Token" } } } }