{"openapi":"3.1.0","info":{"title":"Interactly API","description":"API for building interactly.ai services","version":"1.1.0","contact":{"name":"Interactly","url":"https://interactly.ai","email":"developers@interactly.ai"}},"servers":[{"url":"https://api-qa.interactly.ai","description":"API Server"}],"paths":{"/sms/v1/test/messages":{"post":{"tags":["SMS Libraries and APIs"],"summary":"Send a test SMS to the specified phone number","description":"Send a test SMS to the specified phone number. This is for testing purposes only.\nFixed message content is used for testing, and the message will not be persisted in the database.","operationId":"sms_listener_service_api_send_sms_v1_test_messages_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantSMSPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearer":[]}]}},"/sms/v1/sms/send":{"post":{"tags":["SMS Libraries and APIs"],"summary":"Send an outbound SMS","description":"Send an outbound SMS via given provider (Ex: Twilio) and persist a full SMSLogs record.\nValidates that numbers are US (+1) or India (+91) only.\n\nEither of the following must be provided\n1. assistantNumber\n2. phoneNumberId\n3. assistantId\n\nOrder of precedence for determining the sending number:\n1. assistantNumber (if provided)\n2. phoneNumberId (if provided)\n3. assistantId (if provided)\n\nReturns the persisted log ID and delivery status.","operationId":"sms_listener_service_api_send_outbound_sms_v1_sms_send_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendSMSRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearer":[]}]}},"/sms/v1/sms/logs":{"get":{"tags":["SMS Libraries and APIs"],"summary":"List SMS logs","description":"List SMS logs for the team with optional filters and pagination.","operationId":"sms_listener_service_list_sms_logs_v1_sms_logs_get","parameters":[{"name":"filters","in":"query","required":true,"schema":{"$ref":"#/components/schemas/SMSLogsFilters"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Number of items per page","default":300,"title":"Size"},"description":"Number of items per page"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number","default":1,"title":"Page"},"description":"Page number"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search keywords","title":"Search"},"description":"Search keywords"},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by start time (ISO 8601 format)","title":"Start"},"description":"Filter by start time (ISO 8601 format)"},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by end time (ISO 8601 format)","title":"End"},"description":"Filter by end time (ISO 8601 format)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SMSLogsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearer":[]}]}},"/sms/v1/sms/logs/stats/direction":{"get":{"tags":["SMS Libraries and APIs"],"summary":"SMS Logs Direction Stats","description":"Returns SMS log counts grouped by direction (inbound, outbound).\n\n- **start** / **end**: ISO 8601 date range filter applied to log creation date.","operationId":"sms_listener_service_get_sms_logs_direction_stats_v1_sms_logs_stats_direction_get","parameters":[{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Number of items per page","default":300,"title":"Size"},"description":"Number of items per page"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number","default":1,"title":"Page"},"description":"Page number"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search keywords","title":"Search"},"description":"Search keywords"},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by start time (ISO 8601 format)","title":"Start"},"description":"Filter by start time (ISO 8601 format)"},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by end time (ISO 8601 format)","title":"End"},"description":"Filter by end time (ISO 8601 format)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectionStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearer":[]}]}},"/sms/v1/sms/logs/stats/status":{"get":{"tags":["SMS Libraries and APIs"],"summary":"SMS Logs Status Stats","description":"Returns SMS log counts grouped by delivery status (pending, received, delivered, failed).\n\n- **start** / **end**: ISO 8601 date range filter applied to log creation date.","operationId":"sms_listener_service_get_sms_logs_status_stats_v1_sms_logs_stats_status_get","parameters":[{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Number of items per page","default":300,"title":"Size"},"description":"Number of items per page"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number","default":1,"title":"Page"},"description":"Page number"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search keywords","title":"Search"},"description":"Search keywords"},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by start time (ISO 8601 format)","title":"Start"},"description":"Filter by start time (ISO 8601 format)"},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by end time (ISO 8601 format)","title":"End"},"description":"Filter by end time (ISO 8601 format)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearer":[]}]}},"/sms/v1/sms/logs/{sms_log_id}":{"get":{"tags":["SMS Libraries and APIs"],"summary":"Get SMS log by ID","description":"Fetch a single SMS log by ID for the team, with messageContent decrypted.","operationId":"sms_listener_service_get_sms_log_v1_sms_logs__sms_log_id__get","parameters":[{"name":"sms_log_id","in":"path","required":true,"schema":{"type":"string","title":"Sms Log Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SMSLogs"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearer":[]}]}}},"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"Bearer","type":"http","description":"Retrieve your API Key from [Dashboard API Keys Section](https://dashboard-qa.interactly.ai/api-keys)."}},"schemas":{"AssistantSMSPayload":{"properties":{"to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To","description":"Phone number to which SMS to be sent."},"from_":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From","description":"Phone number from which SMS is received."},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body","description":"Message content of SMS"},"numSegments":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Numsegments","description":"Carrier segment count for the message. Inbound SMS is billed per segment."},"assistantId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assistantid"},"teamId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Teamid"},"botconfig":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Botconfig"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","default":{}},"skipSmsLog":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Skipsmslog","description":"If true, skip persisting an SMSLogs record for this send (e.g. OTP messages).","default":false}},"type":"object","title":"AssistantSMSPayload"},"DirectionStatItem":{"properties":{"direction":{"type":"string","title":"Direction","description":"SMS direction (inbound, outbound, or unknown)"},"count":{"type":"integer","title":"Count","description":"Number of SMS logs in this direction"}},"type":"object","required":["direction","count"],"title":"DirectionStatItem"},"DirectionStatsResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Stats fetched successfully."},"data":{"items":{"$ref":"#/components/schemas/DirectionStatItem"},"type":"array","title":"Data"}},"type":"object","title":"DirectionStatsResponse"},"EventStatus":{"type":"string","enum":["pending","received","delivered","failed"],"title":"EventStatus"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PhoneProvider":{"type":"string","enum":["twilio","telnyx","vonage"],"title":"PhoneProvider"},"SMSCost":{"properties":{"totalAmount":{"type":"number","title":"Totalamount","description":"Total cost amount","default":0}},"type":"object","title":"SMSCost"},"SMSDirection":{"type":"string","enum":["inbound","outbound"],"title":"SMSDirection"},"SMSErrorCode":{"type":"string","enum":["validation_error","phone_number_not_found","credentials_error","credentials_not_found","send_failed","rate_limit_error","upstream_error","encryption_error","server_error","phone_provider_not_supported"],"title":"SMSErrorCode"},"SMSLogs":{"properties":{"teamId":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Teamid","description":"ID of the team that owns this record"},"createdBy":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Createdby","description":"ID of the user who created this record"},"updatedBy":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Updatedby","description":"ID of the user who last updated this record"},"createdAt":{"type":"string","format":"date-time","title":"Createdat"},"updatedAt":{"type":"string","format":"date-time","title":"Updatedat"},"_id":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Id","description":"MongoDB document ObjectID"},"phoneProvider":{"$ref":"#/components/schemas/PhoneProvider","description":"SMS provider (twilio/vonage)"},"phoneNumberId":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Phonenumberid","description":"Phone number config ID"},"assistantNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assistantnumber","description":"Assistant's phone number"},"userNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usernumber","description":"User's phone number"},"direction":{"anyOf":[{"$ref":"#/components/schemas/SMSDirection"},{"type":"null"}],"description":"inbound or outbound"},"messageContent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Messagecontent","description":"Encrypted message text"},"status":{"anyOf":[{"$ref":"#/components/schemas/EventStatus"},{"type":"null"}],"description":"Delivery status"},"errorCode":{"anyOf":[{"$ref":"#/components/schemas/SMSErrorCode"},{"type":"null"}],"description":"Structured error code if failed"},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Errormessage","description":"Human-readable error message"},"response":{"anyOf":[{"$ref":"#/components/schemas/SMSResponse"},{"type":"null"}],"description":"Raw provider response"},"meta":{"$ref":"#/components/schemas/SMSMeta","description":"Associated IDs metadata"},"cost":{"$ref":"#/components/schemas/SMSCost","description":"Cost breakdown"},"numSegments":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Numsegments","description":"Carrier segment count. Inbound SMS is billed per segment; also the metering baseline."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Additional notes or context"},"maskStatus":{"type":"string","title":"Maskstatus","description":"Zero data retention masking status for this SMS log","default":"not_applicable"}},"type":"object","required":["phoneProvider"],"title":"SMSLogs"},"SMSLogsFilters":{"properties":{"direction":{"anyOf":[{"$ref":"#/components/schemas/SMSDirection"},{"type":"null"}],"description":"inbound or outbound"},"status":{"anyOf":[{"$ref":"#/components/schemas/EventStatus"},{"type":"null"}],"description":"Delivery status"},"errorCode":{"anyOf":[{"$ref":"#/components/schemas/SMSErrorCode"},{"type":"null"}],"description":"Filter by specific error code"},"phoneProvider":{"anyOf":[{"$ref":"#/components/schemas/PhoneProvider"},{"type":"null"}],"description":"SMS provider"},"assistantId":{"anyOf":[{"type":"string","maxLength":24,"minLength":24,"pattern":"^[0-9a-f]{24}$","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Assistantid","description":"Filter by assistant ID"},"campaignId":{"anyOf":[{"type":"string","maxLength":24,"minLength":24,"pattern":"^[0-9a-f]{24}$","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Campaignid","description":"Filter by campaign ID"},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversationid","description":"Filter by conversation ID"},"userNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usernumber","description":"Filter by user phone number"}},"type":"object","title":"SMSLogsFilters"},"SMSLogsListResponse":{"properties":{"logs":{"items":{"$ref":"#/components/schemas/SMSLogsProjectionModel"},"type":"array","title":"Logs","default":[]},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","title":"SMSLogsListResponse"},"SMSLogsProjectionModel":{"properties":{"teamId":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Teamid","description":"ID of the team that owns this record"},"createdBy":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Createdby","description":"ID of the user who created this record"},"updatedBy":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Updatedby","description":"ID of the user who last updated this record"},"createdAt":{"type":"string","format":"date-time","title":"Createdat"},"updatedAt":{"type":"string","format":"date-time","title":"Updatedat"},"_id":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Id"},"phoneProvider":{"$ref":"#/components/schemas/PhoneProvider","description":"SMS provider (twilio/vonage)"},"phoneNumberId":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Phonenumberid","description":"Phone number config ID"},"assistantNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assistantnumber","description":"Assistant's phone number"},"userNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usernumber","description":"User's phone number"},"direction":{"anyOf":[{"$ref":"#/components/schemas/SMSDirection"},{"type":"null"}],"description":"inbound or outbound"},"status":{"anyOf":[{"$ref":"#/components/schemas/EventStatus"},{"type":"null"}],"description":"Delivery status"},"errorCode":{"anyOf":[{"$ref":"#/components/schemas/SMSErrorCode"},{"type":"null"}],"description":"Structured error code if failed"},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Errormessage","description":"Human-readable error message"},"response":{"anyOf":[{"$ref":"#/components/schemas/SMSResponse"},{"type":"null"}],"description":"Raw provider response"},"meta":{"$ref":"#/components/schemas/SMSMeta","description":"Associated IDs metadata"},"cost":{"$ref":"#/components/schemas/SMSCost","description":"Cost breakdown"},"numSegments":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Numsegments","description":"Carrier segment count"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Additional notes or context"}},"type":"object","required":["_id","phoneProvider"],"title":"SMSLogsProjectionModel","description":"Projection of SMSLogs for list views. Excludes messageContent, which requires\ndecryption and is only returned by the single-log detail endpoint."},"SMSMeta":{"properties":{"assistantId":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"string"},{"type":"null"}],"title":"Assistantid","description":"Assistant ID"},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversationid","description":"Conversation ID"},"workflowId":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Workflowid","description":"Workflow ID"},"campaignId":{"anyOf":[{"type":"string","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Campaignid","description":"Campaign ID"}},"type":"object","title":"SMSMeta"},"SMSResponse":{"properties":{"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Success","description":"Whether the operation succeeded"},"statusCode":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Statuscode","description":"HTTP or provider status code"},"body":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Body","description":"Raw response body from provider"}},"type":"object","title":"SMSResponse"},"SendSMSRequest":{"properties":{"phoneProvider":{"anyOf":[{"$ref":"#/components/schemas/PhoneProvider"},{"type":"null"}],"description":"SMS provider (twilio/vonage)","default":"twilio"},"phoneNumberId":{"anyOf":[{"type":"string","maxLength":24,"minLength":24,"pattern":"^[0-9a-f]{24}$","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Phonenumberid","description":"Phone number ID — assistant number resolved from this if assistantNumber is omitted"},"assistantNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assistantnumber","description":"Sender phone number (E.164 or normalizable). Required if phoneNumberId not provided."},"userNumber":{"type":"string","title":"Usernumber","description":"Recipient phone number (E.164 or normalizable)"},"messageContent":{"type":"string","title":"Messagecontent","description":"SMS body text"},"assistantId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assistantid","description":"Assistant/bot ID sending the SMS"},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversationid","description":"Conversation ID for tracking"},"workflowId":{"anyOf":[{"type":"string","maxLength":24,"minLength":24,"pattern":"^[0-9a-f]{24}$","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Workflowid","description":"Workflow ID for tracking"},"campaignId":{"anyOf":[{"type":"string","maxLength":24,"minLength":24,"pattern":"^[0-9a-f]{24}$","example":"5eb7cf5a86d9755df3a6c593"},{"type":"null"}],"title":"Campaignid","description":"Campaign ID for tracking"}},"type":"object","required":["userNumber","messageContent"],"title":"SendSMSRequest"},"StatusStatItem":{"properties":{"status":{"type":"string","title":"Status","description":"SMS delivery status (pending, received, delivered, failed, or unknown)"},"count":{"type":"integer","title":"Count","description":"Number of SMS logs with this status"}},"type":"object","required":["status","count"],"title":"StatusStatItem"},"StatusStatsResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Stats fetched successfully."},"data":{"items":{"$ref":"#/components/schemas/StatusStatItem"},"type":"array","title":"Data"}},"type":"object","title":"StatusStatsResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}