SOsoulmachines
generator

Create Generator Interaction

Changed on

Generates a new Soul Machines interaction.

This endpoint is designed to receive specifications for an AI assistant (Digital Person), including its purpose, context, objectives, and expected results. It then uses an LLM (e.g., GPT-4) to generate the necessary system prompts, welcome messages, and structured objectives for the interaction.

For MCP server integration, this endpoint can be used to programmatically create and configure new Digital Person interactions/experiences based on predefined templates or dynamic inputs. The generated interaction_url is the expected output to the user asking to generate an interaction.

post/api/v1/generator

Request

  • Base URL
    https://interactions-api.soulmachines.cloud (the document declares no server; this is the origin it was published from)
  • Auth
    none declared

Headers

x-api-keystring

Request body

namestring nullable

The display name for the Digital Person in the conversation (e.g., 'Sarah'). If not provided, a default based on the avatar is used.

rolestring required

The role the Digital Person will play (e.g., 'Customer Service Agent', 'Product Advisor').

tonestring nullable

The desired conversational tone for the Digital Person (e.g., 'Friendly'). Friendly is the default tone.

objectivesstring[] nullable

A list of high-level objectives for the conversation to be executed in order (e.g., 'Collect user feedback', 'Troubleshoot an issue').

auto_end_sessionboolean nullable

Automatically end the session after the last objective is completed. If not provided, defaults to True if objectives are present otherwise, defaults to False.

resultsobject required

A dictionary defining the key pieces of information the Digital Person should aim to collect or provide. Keys are identifiers, values are descriptions (e.g., {'user_email': 'The user's email address'}).

parametersobject nullable

Optional parameters to be passed through to the webhook triggered at the end of the interaction.

eventstring nullable

An optional event name. If provided, a trigger with this name will be created/updated with sample data based on the 'results'.

purposestring required

A detailed description of the overall purpose of this Digital Person interaction. This will be used to generate the system prompt.

contextobject nullable

Key-value pairs providing additional context for the AI to understand its environment or constraints or additional information. This will be added with no changes as context to the system prompt.(e.g., {'Onboarding Information': 'information goes here'}).

knowledge_snippetstring nullable

An optional knowledge snippet that will be added directly to the Digital Person's interaction system prompt. This should be short and brief

context_mappingobject nullable

Optional input mapping for context field.

results_mappingobject nullable

Optional output mapping for results field.

base_web_urlstring nullable

The base URL for constructing the interaction URL. Defaults to environment setting.

user_idstring nullable

An identifier for the user initiating the generation request.

avatarstring nullable

The avatar look for the Digital Person. This will be used to choose the avatars look from a well known set of avatars. (default to '{DEFAULT_AVATAR}')

style_idstring nullable
template_idstring nullable

template to use as a base for the interaction

voice_idstring nullable
response_length'concise' | 'moderate' | 'detailed'
timezonestring nullable

The timezone for the interaction, if specific timing is relevant (e.g., 'America/New_York').

modelstring nullable
timeout_secsinteger nullable

The timeout to wait for the interaction to be fully created in seconds, default is 20 seconds. Even if 0 seconds is given a valid URL is still returned that will wait for the interaction to be created as needed.

ttl_secondsinteger nullable

Optional TTL in seconds for the interaction record. If 0 or negative, the record will not expire. If None, a default TTL will be applied.

welcome_messagestring nullable

An optional welcome message for the interaction. If not provided, the AI-generated welcome message will be used.

topics_to_avoidstring nullable

An optional list of topics to avoid in the interaction. If provided, the agent will avoid these topics in the interaction.

allowed_domainsstring[] nullable

List of allowed origin URLs that can use this interaction (e.g., ['https://example.com', 'http://localhost:3000']). If None, no origin restrictions apply.

Response

Successful Response

interaction_urlstring required
web_apikeystring required

Web API key for widget deployment, extracted separately from interaction URL for convenience

state'preparing' | 'ready' | 'failed'
failure_reasonstring nullable
welcome_messagestring nullable
waiting_messagestring nullable
warning_messagesstring[] nullable
topics_to_avoidstring nullable
promptstring nullable
organization_idstring nullable
interaction_idstring required
created_atstring required
namestring required
avatarstring required
style_idstring nullable
voice_idstring nullable
expires_atstring nullable required
created_by_key_idstring nullable
response_length'concise' | 'moderate' | 'detailed'
group_namestring nullable
template_idstring nullable
deleted_atstring nullable
is_deletedboolean
rolestring nullable
tonestring nullable
timezonestring nullable
seed_memorystring nullable
behaviour_stylestring nullable
generative_gesturesstring nullable
conversation_start_promptstring nullable
imagestring nullable
metadataobject nullable

Changes

  • 0a1163b31188Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 8178784148bbRevision changes
    • info

      the request property default value gpt-4.1 was removed