Skip to content

Latest commit

 

History

History
703 lines (582 loc) · 28.7 KB

_conversations.md

File metadata and controls

703 lines (582 loc) · 28.7 KB

Conversations

The Conversation API is a resource, that represents a conversational exchange with Structurely. This resource allows you to interface your CRM directly with Structurely.

Create Conversation

curl 'https://api.structurely.com/v1/conversations' \
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "settings": { "timeZone": "America/Chicago", "liveTransferUrl": "https://your-domain/api/structurely-live-transfer-start/leadId" }, "slots": [{ "name": "email", "value": "[email protected]" }, { "name": "lead_type", "value": "buyer" }, { "name": "lead_type", "value": "seller" }, { "name": "external_lead_id", "value": "63dae72910b57fd51d0d9652"}], "messages": []}'

The above command returns JSON structured like this:

{
    "id": "5c09a4416241ea2c293275b8",
    "settings": {
        "chatbotName": "Aisa",
        "timeZone": "America/Chicago",
        "activateGenerativeAi": true,
        "liveTransferUrl": "https://your-domain/api/structurely-live-transfer-start/leadId"
    },
    "slots": [
        {
            "name": "email",
            "value": "[email protected]"
        },
        {
            "name": "lead_type",
            "value": "buyer"
        },
        {
            "name": "lead_type",
            "value": "seller"
        }
    ],
    "muted": false
}

This endpoint creates and returns a new conversation object.

HTTP Request

POST https://api.structurely.com/v1/conversations

Body Parameters[^]

Parameter Type
settings ConversationSettings [^]
slots List<ConversationSlot>
muted Boolean
messages List<ConversationItem>

Extra slots for tracking

Set these optional slots to facilitate reporting and querying of conversations using IDs in your own system. Store these optional IDs by sending them as slots with string values. These IDs are persisted internally but not emitted as slots when conversations are retrieved over the API.

Slot Name Purpose
external_account_id Associate this conversation to its account's ID
external_team_id Associate this conversation to its team's ID
external_user_id Associate this conversation to its user's ID
external_lead_id Associate this conversation to its lead's ID
Be sure to include the header `Content-Type: application/json` with your request.

Get Conversation

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8' \
  -H 'X-Api-Authorization: myapikey'

The above command returns JSON structured like this:

{
    "id": "5c09a4416241ea2c293275b8",
    "settings": {
        "chatbotName": "Aisa",
        "timeZone": "America/Chicago"
    },
    "slots": [
        {
            "name": "name",
            "value": "John Doe"
        },
        {
            "name": "email",
            "value": "[email protected]"
        },
        {
            "name": "phone",
            "value": "+15551234567"
        },
        {
            "name": "address",
            "value": "123 Main St."
        },
        {
            "name": "agent_name",
            "value": "Andi Agent"
        },
        {
            "name": "lead_type",
            "value": "buyer"
        },
        {
            "name": "lead_type",
            "value": "seller"
        }
    ],
    "muted": false
}

This endpoint returns a specific conversation.

HTTP Request

GET https://api.structurely.com/v1/conversations/<id>

URL Parameters

Parameter Description
id The ID of the conversation to retrieve

Response Body[^]

Update Conversation

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8' \
  -X PATCH \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "muted": true }'

The above command returns JSON structured like this:

{
    "id": "5c09a4416241ea2c293275b8",
    "settings": {
        "chatbotName": "Aisa",
        "timeZone": "America/Chicago"
    },
    "slots": [
        {
            "name": "email",
            "value": "[email protected]"
        }
    ],
    "muted": true
}

This endpoint updates and returns a specific conversation object.

HTTP Request

PATCH https://api.structurely.com/v1/conversations/<id>

URL Parameters

Parameter Description
id The ID of the conversation to update

Body Parameters

Parameter Type Description
muted Boolean Once muted, a conversation can still receive messages but will no longer generate replies. It is not possible to unmute a conversation.
Be sure to include the header `Content-Type: application/json` with your request.

Response Body[^]

Insert Slots

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8/slots' \
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '[{ "name": "agent_name", "value": "Andi Agent" }]'

The above command returns an empty body with a 204 response

This endpoint inserts the given slots to the conversation. Multi-valued slots will append the new values rather than replacing them. Returns a 204 response with an empty body.

HTTP Request

POST https://api.structurely.com/v1/conversations/<id>/slots

URL Parameters

Parameter Description
id The ID of the conversation insert slots to

Body Parameters

The body is a list of objects

Type Description
List<ConversationSlot> The list of conversation slot objects
Be sure to include the header `Content-Type: application/json` with your request.

Update Slots

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8/slots' \
  -X PATCH \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '[{ "name": "agent_name", "value": "Andi Agent" }]'

The above command returns an empty body with a 204 response

This endpoint updates the given slots to the conversation. Multi-valued slots will be overwritten with the new values replacing the old ones. Returns a 204 response with an empty body.

HTTP Request

PATCH https://api.structurely.com/v1/conversations/<id>/slots

URL Parameters

Parameter Description
id The ID of the conversation insert slots to

Body Parameters

The body is a list of objects

Type Description
List<ConversationSlot> The list of conversation slot objects
Be sure to include the header `Content-Type: application/json` with your request.

Upsert Slot

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8/slots/agent_name' \
  -X PUT \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '["Andi Agent"]'

The above command returns an empty body with a 204 response

This endpoint updates the exsting slot with that name to the list of values provided. All slots, both multi-valued and single-valued are provided in an array. Make the array a single element array if the slot is single-valued. If the slot does not already exist with that name, it is inserted with all the values provided.

HTTP Request

PUT https://api.structurely.com/v1/conversations/<id>/slots/<name>

URL Parameters

Parameter Description
id The ID of the conversation insert slots to
name The name of the slot to update or insert

Body Parameters

The body is a list of values

Type Description
List<Any> The list of slot values
Be sure to include the header `Content-Type: application/json` with your request.

Create Message

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8/messages'
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "Hello World", "received": "2018-12-09T11:44:00.000Z" }'

The above command returns JSON structured like this:

{
    "_metadata": {
        "conversation": "5c09a4416241ea2c293275b8",
        "messages": 2,
        "responses": 1
    },
    "message": {
        "id": "5c09a45e6241ea2c293275bf",
        "text": "Hello World",
        "received": "2018-12-09T11:44:00.000Z"
    }
}

This endpoint creates a new lead message for the conversation for us to extract and classify.

HTTP Request

POST https://api.structurely.com/v1/conversations/<id>/messages

URL Parameters

Parameter Description
id The ID of the conversation to create a message for

Body Parameters[^]

Parameter Type
text String
received DateTime
Be sure to include the header `Content-Type: application/json` with your request.

Create Response

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8/responses'
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "_metadata": { "context": "expect_showing_appointment" }, "text": "Hello There", "received": "2018-12-09T11:44:00.000Z" }'

The above command returns JSON structured like this:

{
    "_metadata": {
        "conversation": "5c09a4416241ea2c293275b8",
        "context": "expect_showing_appointment",
        "messages": 2,
        "responses": 2
    },
    "response": {
        "id": "5c09a4416241ea2c293275b5",
        "text": "Hello There",
        "received": "2018-12-09T11:44:00.000Z"
    }
}

This endpoint creates a new system response for the conversation. This does nothing in our system other than act as a send receipt notifying us that an outbound message was sent on behalf of the system/realtor.

HTTP Request

POST https://api.structurely.com/v1/conversations/<id>/responses

URL Parameters

Parameter Description
id The ID of the conversation to create a message for

Body Parameters[^]

Parameter Type
_metadata MessageMetaData
text String
received DateTime
Be sure to include the header `Content-Type: application/json` with your request.

Schemas

Conversation

Field Type Description Readable? Writable? Required? Default
id ObjectId The ID of the conversation this resource represents. Yes No No
settings ConversationSettings [^] The settings for to use for this conversation. Yes No Yes
slots List<ConversationSlot> A list of extracted or pre-filled values relating to the conversation. Yes No Yes
muted Boolean A boolean flag to tell whether or not this conversation is muted. Once muted, a conversation can still receive messages but will no longer generate replies. It is not possible to unmute a conversation. Yes Yes No false
stages List<String> A list of stages this conversation is currently in. Yes No No
messages List<ConversationItem> A list of lead messages and system responses with the context value with each response. No No Yes

ConversationSettings

Field Type Description Readable? Writable? Required? Default
timeZone String The time zone the realtor and/or lead. (See list) Yes No Yes
chatbotName String The name of conversation AI to use in responses. Yes No No Aisa
leadTypes List<String> The lead types that will be supported in this conversation. Possible values are buyer, seller, and renter Yes No No ['buyer', 'seller']
allowedDomains List<String> The domains that this conversation can use for conversation flows. Possible values are real_estate and mortgage. When a lead sets or changes its lead type, the domain determines what scripts to use. Yes No No ['real_estate']
dripCampaignEnabled Boolean If set to true, Structurely drip campaigns will be used for an unresponsive lead. Only runs if there is no lead message following a system response in the messages list. Yes No No false
reDripsEnabled Boolean If set to true, Structurely will re-engage leads that have responded but are not responding to the current prompt. Will use the current context to determine outbound re-drips even if a custom response is generated by the third party user. Yes No No false
activateGenerativeAi Boolean If set to true, Structurely will use Generative AI to enhance scripted responses, which results in better conversations and lower carrier filtering. Yes No No false
liveTransferUrl URL Enables Live Transfer, must be a valid URL using https:// Yes No No undefined
liveTransferStatusUpdateUrl URL Sends Live Transfer status reports, must be a valid URL using https:// Yes No No undefined

ConversationSlot

Field Type Description Readable? Writable? Required?
name[a] String The name of the slot. Yes No Yes
value[a] Any The value of the slot. Yes No Yes

ConversationItem

Field Type Description Readable? Writable? Required?
message Message A message the lead sent. No Yes Yes[1]
respone Message A respone sent by the system. No Yes Yes[1]
context[b] String The context set by the response in this conversation item. No Yes Yes[2]
  1. message and response are mutually exclusive. At least one is required to be present but not both.
  2. context is only required if the response field is used.

Message

Field Type Description Readable? Writable? Required?
text String The text of the message. No Yes Yes
received DateTime The time the message was sent or received. No Yes Yes
_metadata[1] MessageMetaData An optional metadata object to set the outgoing context for a response. No Yes No
  1. _metadata is only used when creating a response object.

MessageMetaData

Field Type Description Readable? Writable? Required?
context String The outgoing context of this response. Used by Structurely to classify messages sent after this response. No Yes No

Slots, Contexts, and Stages

Slots

Name Type Description
Lead Contact Information
name String The name of the lead.
email String The email of the lead.
phone String The phone number of the lead.
address String The address of the property a buyer lead is interested in.
selling_address String The address of the property a seller lead is trying to sell.
lead_type List<String> A list of lead types this lead is considered as. Not limited to but includes any of buyer, buyer_specific, renter, renter_specific, seller, just_looking, pending_sale_interest, investor, rent_to_own, rent_to_own_specific, new_home_loan, new_home_loan_specific, home_refinance or a combination thereof.
Agent Contact Information
agent_name String The name of the agent Structurely is messaging on the behalf of.
agent_email String The email of the agent.
agent_phone String The phone of the agent.
agency_name String The name of the agency the agent works for or Structurely is messaging on the behalf of.
office_location String The general location of the realtor office the system is representing.
Slots for Tracking Purposes
external_account_id String Associate this conversation to its account's ID
external_team_id String Associate this conversation to its team's ID
external_user_id String Associate this conversation to its user's ID
external_lead_id String Associate this conversation to its lead's ID
General Lead Information
agent_status Boolean True if the lead is already working with an agent.
alternate_plan String
appointment String The time the lead is available for an appointment.
baths Float The specific number bathrooms the lead is looking for.
baths_min Float The minimum number of bathrooms the lead is looking for.
baths_max Float The maximum number of bathrooms the lead is looking for.
beds Integer The specific number of bedrooms the lead is looking for.
beds_min Integer The minimum number of bedrooms the lead is looking for.
beds_max Integer The maximum number of bedrooms the lead is looking for.
benefit Boolean
business_development Enum Business development. Possible values:
{'outbound', 'inbound', 'paid', 'referral', 'networking'}
call_availability String The time when the lead is available for a call with the agent.
company_name String
competitor_status Boolean
confidence Enum Confidence. Possible values:
{'very_confident', 'somewhat_confident', 'not_confident'}
contact_confirmation Boolean
contact_time String
content_offer Boolean
contingency Boolean True if the lead needs to sell their current home before buying.
credit Enum Credit rating. Possible values:
{'very_poor', 'fair', 'good', 'very_good', 'excellent'}
credit_score Integer[300,850]
debt_to_income Float[0,50]
decision_maker Boolean
decision_process String
delivery_followup Boolean
description String
down_payment Float
down_payment_min Float
down_payment_max Float
employment_status Enum Employment status. Possible values:
{'self_employed', 'employed', 'not_employed'}
equity_status Float
equity_status_min Float
equity_status_max Float
favorite_city String
financial_default Enum Financial default. Possible values:
{'bankruptcy', 'foreclosure', 'short_sale', 'missed_payments'}
financing_status Boolean True if the lead is prequalified or paying with cash.
first_time_buyer Boolean
fsbo_reason String
garage_stalls Integer[0,8] Number of garage stalls.
garage_stalls_min Integer[0,8] Minimum number of garage stalls.
garage_stalls_max Integer[0,8] Maximum number of garage stalls.
home_style Enum The home style(s) the lead is interested in. Possible values:
{'art_deco', 'barndominium', 'bungalow', 'cape_cod', 'colonial', 'condominium', 'contemporary', 'craftsman', 'creole', 'dutch_colonial', 'farmhouse', 'federal', 'french_provincial', 'georgian', 'gothic_revival', 'greek_revival', 'international', 'italianate', 'log_cabin', 'modern', 'monterey', 'national', 'neoclassical', 'prairie', 'pueblo', 'queen_anne', 'ranch', 'regency', 'saltbox', 'second_empire', 'shed', 'shingle', 'shotgun', 'spanish_eclectic', 'split_level', 'stick', 'tudor', 'victorian', 'other'}
image String
income Float
interest Enum Interest. Possible values:
{'interested', 'not_interested', 'somewhat_interested', 'postponed_interested'}
is_agent Boolean True if the lead is an agent.
is_investor Boolean True if the lead is an investor buying property.
is_local Boolean
language Enum The language detected in this conversation. Current conversation support is for English and Spanish languages only. Possible values:
{'spanish', 'mandarin', 'french', 'hindi', 'arabic', 'portuguese', 'bengali', 'russian', 'japanese', 'punjabi', 'english'}
lead_priority Enum Lead priority. Possible values:
{'now', 'soon', 'later', 'distant', 'never'}
lead_source String The source of the lead. Can be any string.
lender_status Boolean
listing_appointment String The time the lead is available for an appointment about their listing.
listing_url String
living_space Integer The living space the lead is searching for.
living_space_min Integer The minimum living space the lead is searching for.
living_space_max Integer The maximum living space the lead is searching for.
loan_balance Integer The loan balance.
loan_balance_min Integer The minimum loan balance.
loan_balance_max Integer The maximum loan balance.
loan_type Enum Loan type. Possible values:
{'fha', 'conventional', 'va', 'reverse_mortgage', 'jumbo', 'usda'}
location String The general location the lead is interested in buying.
lot_size Integer The lot size the lead is searching for.
lot_size_min Integer The minimum lot size the lead is searching for.
lot_size_max Integer The maximum lot size the lead is searching for.
meeting_location String Special values:
webcam, zoom, google_hangouts, uberconference, open
military_active_duty Boolean
military_branch Enum Possible values:
{'army', 'air_force', 'coast_guard', 'marines', 'navy', 'national_guard', 'space_force'}
military_discharge_type Enum Possible values:
{'honorable_discharge', 'general_discharge', 'other_than_honorable_discharge', 'bad_conduct_discharge', 'dishonorable_discharge', 'entry_level_separation', 'medical_separation', 'separation_for_convenience_of_the_government'}
military_reserves_service Boolean
military_service_term Integer
mortgage_escrow Boolean
mortgage_intent Enum Possible values:
{'preapproval', 'rate_quote'}
motivation Enum Possible values:
{'new_job', 'lost_job', 'downsizing', 'upsizing', 'death', 'debt', 'divorce', 'lease_expiry', 'lifestyle', 'investment', 'environmental', 'save_money', 'closer_to_family', 'tired_of_renting', 'new_children', 'retiring', 'space_for_animals', 'neighbor_sold_property', 'sold_property', 'ready_to_move', 'closer_to_school', 'closer_to_friends', 'good_schools', 'vacation_interest', 'homeless', 'privacy', 'weather'}
motivation_plans String
outcome String
ownership Enum Possible values:
{'sole_owner', 'co_owner', 'third_party_owner', 'no_ownership'}
ownership_timeline String Special value: open
price Float The specific price the lead is looking for.
price_min Float The minimum price the lead is looking for.
price_max Float The maximum price the lead is looking for.
prior_loan_experience Boolean
problem String
promotional_offer Enum Interest. Possible values:
{'interested', 'not_interested', 'somewhat_interested', 'postponed_interested'}
property_feature Enum Possible values:
{'access_to_water', 'big_yard', 'detached_garage', 'exposed_beams', 'exposed_brick', 'finished_basement', 'handicap_accessible', 'home_office', 'pool', 'space_to_entertain', 'updated_baths', 'updated_kitchen', 'vaulted_ceilings', 'walkable_neighborhood', 'fenced_yard', 'other'}
property_info_request Enum Possible values:
{'baths', 'beds', 'boat_slip', 'community_info', 'covenants', 'days_on_market', 'deed_restrictions', 'disclosures', 'expected_dom', 'floorplan', 'garage_spaces', 'hoa', 'living_space', 'lot_rent', 'lot_size', 'owners', 'pet_friendly', 'price', 'property_location', 'property_type', 'public_remarks', 'rental_history', 'schools', 'senior_community', 'status', 'stories', 'taxes', 'transactions', 'utilities', 'year_built', 'zoning'}
property_location String
property_preferences String
property_records Enum Possible values:
{'second_mortgage', 'lien'}
property_status Enum Possible values:
{'active', 'sold', 'pending'}
property_type Enum Possible values:
{'vacant_land', 'handicap_accessible', 'commercial', 'apartment', 'mobile_home', 'acreage', 'ranch', 'vacation_home', 'residential'}
property_use Enum Property use. Possible values:
{'vacation', 'investment', 'primary_residence', 'secondary_residence', 'agriculture'}
property_value Float
property_value_min Float
property_value_max Float
property_visit Boolean
question Enum The question that the lead just asked. Possible values:
{'pricing', 'integrations', 'how_it_works', 'features', 'setup_time', 'savings', 'repairs', 'results', 'consultation', 'leasing', 'delivery_time', 'competitive_advantage', 'product_requirements', 'specifications', 'incentives', 'warranty', 'return_on_investment', 'discounts', 'assembly_details', 'referrals', 'compliance', 'available_geography', 'upgrade', 'extension', 'company_details', 'sell_power_back', 'inverter_type', 'license_number', 'data_import', 'quote', 'taxes', 'schools', 'other'}
readiness Enum The readiness of the lead. Possible values:
{'active', 'just_looking', 'researching', 'not_interested', ''}
relocating Boolean
savings Float
savings_min Float
savings_max Float
selling_property_description String
showing_appointment String The time the lead is available for a showing appointment.
tags String General purpose tags for managing and tracking conversations. Will not be asked as a qualifier and is not used to generate responses.
technology String Special value: open
tenure String
time String Special value: open
timeframe String The general timeframe a lead is looking to move within.
url String
veteran Boolean
veteran_service_disability Boolean
work_history String

Contexts

Name
general
expect_address
expect_agent_status
expect_alternate_plan
expect_appointment
expect_baths
expect_beds
expect_business_development
expect_call_availability
expect_company_name
expect_competitor_status
expect_confidence
expect_contact_confirmation
expect_contact_time
expect_contingency
expect_credit
expect_credit_score
expect_debt_to_income
expect_decision_maker
expect_delivery_followup
expect_description
expect_down_payment
expect_email
expect_employment_status
expect_equity_status
expect_financial_default
expect_financing_status
expect_first_time_buyer
expect_fsbo_reason
expect_garage_stalls
expect_image
expect_income
expect_interest
expect_is_local
expect_language
expect_lead_type
expect_listing_appointment
expect_living_space
expect_loan_balance
expect_location
expect_lot_size
expect_meeting_location
expect_military_active_duty
expect_military_branch
expect_military_discharge_type
expect_military_reserves_service
expect_military_service_term
expect_mortgage_escrow
expect_mortgage_intent
expect_motivation
expect_motivation_plans
expect_name
expect_outcome
expect_ownership
expect_ownership_timeline
expect_phone
expect_preferred_channel
expect_price
expect_prior_loan_experience
expect_problem
expect_product_interest
expect_promotional_offer
expect_property_feature
expect_property_location
expect_property_preferences
expect_property_records
expect_property_status
expect_property_type
expect_property_value
expect_question
expect_readiness
expect_relocating
expect_savings
expect_selling_address
expect_showing_appointment
expect_time
expect_timeframe
expect_url
expect_veteran
expect_veteran_service_disability

Stages

Name Description
not_responded The lead has not responded in this conversation.
responded The lead has responded in this conversation.
not_interested The lead has indicated no interest or opted out of communication in this conversation.
interested The lead has responded and has not been classified as not interested.
needs_follow_up The lead has reached a conclusion in the conversation that requires further follow-up.

Domains

To use domains other than the default real_estate domain, the domains have to be enabled in the settings and an appropriate lead type has to be selected in the lead_type slot. An example of using the mortgage scripts for a new home loan buyer would be to set the allowedDomains settings value to ["real_estate", "mortgage"] and setting the lead_type slot to the values "buyer" and "new_home_loan".