create_research_trigger
ChatGPTCreate a paused in-product research trigger that invites a user to an interview right after a product moment, such as a failed action, churn event, or onboarding step. Returns activation_url. Created paused; a person opens activation_url to activate. delivery_method defaults to intercept (in-app prompt). webhook posts each match to webhook_url. Unsupported filters are rejected. This tool cannot activate the trigger or send the invite.
create_study
ChatGPTCreate an interview study when you already know what happened and still need to learn why. Returns study_id and interview_link. Do not share the link yet. Call list_studies first and reuse a study that already asks this question. key_research_goal is required. business_context is optional. One active agent study per account. On 402, surface checkout_url to a human. This does not run the interview. Call simulate_interview next.
delete_research_trigger
ChatGPTPermanently delete an in-product research trigger. Interviews already completed stay on the study, including their themes and quotes. Cannot be undone. Does not delete the interview study. A paused trigger stops new invites and keeps the trigger.
delete_study
ChatGPTPermanently delete an interview study, its recordings, and unused reserved credits. Cannot be undone. Does not delete in-product research triggers.
get_research_trigger
ChatGPTRead one in-product research trigger by trigger_id, including who it invites and how many interviews it has started. Returns status, targeting, activation_url, and invite and interview counts. activation_url is present while the trigger is paused. Does not change the trigger, cannot activate it, and does not return themes or quotes.
get_study_results
ChatGPTGet interview findings after real users have talked: themes, insights, risks, and verbatim quotes. format omitted or summary returns themes, insights, and risks. format=full also returns transcripts. Empty themes mean analysis is not ready. Does not create interviews or edit the guide.
get_study_status
ChatGPTCheck interview progress. not_started means no interview has started. running means interviews are underway. analyzing means results are still processing. Returns completed_interviews, target_interviews, interview_link, and next_step. not_started, running, and analyzing include no findings, themes, or quotes. Does not change the study.
get_trigger_capabilities
ChatGPTSee which in-product research trigger conditions this account can use. Returns supported and unsupported kinds. Supported: one product event, an exact property or trait match, a URL rule, and page dwell. Unsupported: counts, sequences, absence, time windows, and not-equals. Does not create a trigger.
get_trigger_event_schema
ChatGPTRead the fields observed on one product event so a trigger can match a property or user trait. Returns each field's type and sample values. Filters are exact matches and are case-sensitive and type-sensitive. Values that were not observed are absent. Does not create a trigger.
get_trigger_sdk_setup
ChatGPTGet the snippet that sends product events, such as a failed action, onboarding step, or churn signal, into Usercall for in-product interviews. Returns install_snippet, identify_snippet, allowlist_update_snippet, and install status. provider defaults to posthog. events names the allowlist. The response does not include secret keys. Does not create a trigger.
list_research_triggers
ChatGPTList in-product research triggers that invite users to an interview after a product event. Returns status and activation_url for each. activation_url is present while a trigger is paused and empty after a person activates it. Does not change a trigger and cannot activate one.
list_studies
ChatGPTList interview studies on this account so an existing question about churn, onboarding, or a failed action can be reused. Returns study_id, interview_link, interview_mode, and trigger_eligible. trigger_eligible is false when the study has no interview link. Does not create or edit a study.
list_trigger_events
ChatGPTList product event names Usercall has received in the last 30 days, such as a failed action or onboarding step. Returns those names. A research trigger accepts only an observed event name. An empty list means no events have arrived. Does not create a trigger.
review_study
ChatGPTCheck the interview guide before sharing it with a real participant. Use this when you want a read of the guide only. It does not read transcripts and it does not apply edits. It costs 1 credit and works when the in-app review control is hidden. On 402, surface checkout_url to a human. Write suggested changes with update_study. Stop after one review unless the guide changed. This is not simulate_interview and it is not get_study_results.
simulate_interview
ChatGPTDry-run an interview guide before a real participant joins, including a question about churn, onboarding, or a failed action. Omit simulation_id to start; returns immediately with status running and a simulation_id. Pass simulation_id to read that run. Result status is pass, fail, or error. Max 5 simulations per account per UTC day. HTTP 429 means the daily cap is reached. Omit persona and the server writes a participant from the research question and the guide. A persona, when sent, includes both name and prompt. A dry-run does not change completed_interviews and does not invite a participant.
update_research_trigger
ChatGPTUpdate who an in-product interview trigger invites: product event, trait or property match, sampling, cooldown, daily cap, prompt copy, or delivery. Returns the updated trigger. status paused pauses it. status active is rejected with HTTP 409 and activation_url; a person opens that URL to activate. Editing an active trigger pauses it until a person approves it again. Does not activate a trigger.
update_study
ChatGPTUpdate an interview study: slots, guide questions, intro, languages, voice, or an image or Figma prototype shown to participants. Returns the updated study. key_research_goal cannot be changed. is_link_disabled true stops new interviews and keeps recordings. One locale hides the language picker; two or more show it. Query parameters on interview_link are ignored until enable_link_context is true. study_media null clears media. API errors include http_status. Does not dry-run the guide or invite a participant.
