{"openapi":"3.1.0","info":{"title":"FluidTalk Characters API","description":"Public API for integrating external bots with FluidTalk Characters. Authenticate with your per-character connector token in the X-Connector-Token header.","version":"v1"},"paths":{"/api/v1/characters/chat":{"post":{"tags":["characters-v1"],"summary":"Send a lead's message and get the character's reply","operationId":"v1_chat_api_v1_characters_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/characters/events":{"post":{"tags":["characters-v1"],"summary":"Report a purchase / refund / chargeback (idempotent)","operationId":"v1_events_api_v1_characters_events_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/characters/triggers":{"post":{"tags":["characters-v1"],"summary":"Fire a conversation trigger (story reaction / new follower / custom)","operationId":"v1_triggers_api_v1_characters_triggers_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/characters/followups":{"get":{"tags":["characters-v1"],"summary":"Pull pending proactive follow-up messages","operationId":"v1_followups_api_v1_characters_followups_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","default":"","title":"Platform"}},{"name":"own_username","in":"query","required":false,"schema":{"type":"string","default":"","title":"Own Username"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Too Many Requests"}}}},"/api/v1/characters/followups/{followup_id}/ack":{"post":{"tags":["characters-v1"],"summary":"Acknowledge a delivered follow-up","operationId":"v1_followup_ack_api_v1_characters_followups__followup_id__ack_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"followup_id","in":"path","required":true,"schema":{"type":"string","title":"Followup Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Too Many Requests"}}}},"/api/v1/characters/comments":{"post":{"tags":["characters-v1"],"summary":"Generate a public comment on a post","operationId":"v1_comments_api_v1_characters_comments_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/characters/comments/reply":{"post":{"tags":["characters-v1"],"summary":"Generate a reply to a reply on our comment","operationId":"v1_comments_reply_api_v1_characters_comments_reply_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentReplyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"ChatRequest":{"properties":{"platform":{"type":"string","title":"Platform","description":"The platform this conversation is on, e.g. 'instagram'."},"handle":{"type":"string","title":"Handle","description":"The lead's handle/username on that platform."},"message":{"type":"string","title":"Message","description":"The lead's inbound message text.","default":""},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"URL of an image the lead sent (described via vision)."},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Resume a specific session; omit to auto-resume/create."},"own_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Own Username","description":"The bot account that received this DM (mother-slave dedup; aliases account/self_handle)."}},"type":"object","required":["platform","handle"],"title":"ChatRequest"},"CommentPost":{"properties":{"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caption","description":"The post's caption/text."},"image_urls":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Image Urls","description":"The post's image URL(s) (described via vision)."},"author_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Handle","description":"The post author's handle."}},"type":"object","title":"CommentPost"},"CommentReplyRequest":{"properties":{"platform":{"type":"string","title":"Platform"},"post_ref":{"type":"string","title":"Post Ref"},"replier_handle":{"type":"string","title":"Replier Handle","description":"Who replied to our comment."},"reply_text":{"type":"string","title":"Reply Text","description":"Their reply text.","default":""},"parent_comment_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Comment Ref","description":"The comment this is replying to."},"post":{"anyOf":[{"$ref":"#/components/schemas/CommentPost"},{"type":"null"}],"description":"Post context if the thread isn't known yet."}},"type":"object","required":["platform","post_ref","replier_handle"],"title":"CommentReplyRequest"},"CommentRequest":{"properties":{"platform":{"type":"string","title":"Platform"},"post_ref":{"type":"string","title":"Post Ref","description":"The platform's unique id/URL for the post."},"post":{"$ref":"#/components/schemas/CommentPost"}},"type":"object","required":["platform","post_ref","post"],"title":"CommentRequest"},"Envelope":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"},"request_id":{"type":"string","title":"Request Id"}},"type":"object","required":["data","request_id"],"title":"Envelope"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"type":{"type":"string","title":"Type"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"}},"type":"object","required":["code","message","type"],"title":"ErrorBody"},"ErrorEnvelope":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorEnvelope"},"EventRequest":{"properties":{"platform":{"type":"string","title":"Platform"},"handle":{"type":"string","title":"Handle"},"event_type":{"type":"string","title":"Event Type","description":"purchase | refund | chargeback","default":"purchase"},"external_event_id":{"type":"string","title":"External Event Id","description":"Idempotency key — the flip applies exactly once."},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount","description":"Positive amount of money that moved."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO currency code (default USD)."},"raw":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Raw","description":"Connector payload echo (tokens are stripped)."}},"type":"object","required":["platform","handle","external_event_id"],"title":"EventRequest"},"TriggerRequest":{"properties":{"platform":{"type":"string","title":"Platform"},"handle":{"type":"string","title":"Handle"},"event_id":{"type":"string","title":"Event Id","description":"The configured entry-point event key. Unknown = no-op (fail-closed)."},"external_event_id":{"type":"string","title":"External Event Id","description":"Idempotency key — fires exactly once."},"context":{"anyOf":[{},{"type":"null"}],"title":"Context","description":"Short descriptive detail (an emoji / label) for the opener."},"own_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Own Username","description":"The bot account that received this event (dedup)."},"raw":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Raw"}},"type":"object","required":["platform","handle","event_id","external_event_id"],"title":"TriggerRequest"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-Connector-Token"}}}}