Start a conversation
Send the first message to a contact, creating a conversation with them, or adding to the existing one if they have messaged the account before.
Send the first message to a contact, creating a conversation with them, or adding to the existing one if they have messaged the account before. The response carries the conversation and its first message: the message's status shows whether it has been delivered (sent) or is still pending, and message.sent fires once it is delivered. A new conversation fires conversation.started.
Networks limit who a business can message first, so each takes its own fields to address the contact, in an object named after the network.
Network support
- Instagram: pass
instagram.comment_idandinstagram.author_id(both required) to send a private reply to the comment's author. UseaccountId,commentIdandauthorIdfrom thecomment.receivedwebhook associal_account_id,instagram.comment_idandinstagram.author_id. A comment can receive one private reply, within 7 days of it, and nothing more can be sent until the contact replies: until then,POST /v1/conversations/:id/messagesis rejected with 422. Addinstagram.quick_repliesorinstagram.buttonsto give the contact one-tap answers: a tap is their reply, so it opens the 24-hour window.
Permissions: Requires conversations:send. Access is limited by the API key creator's current organization membership and stored key ceiling. See Organization permissions.
application/json- body
Send the first message to a contact, starting a conversation with them
social_account_id*stringThe connected account to send from. To reply to a comment, the account that owns the post (accountId in the comment.received webhook).
1 <= lengthcontent*stringText body of the first message. Media is not supported when starting a conversation.
1 <= lengthinstagram?Instagram-specific fields. Required for an Instagram account: Instagram only lets a business start a conversation with a private reply to a comment.
facebook?Facebook-specific fields. Required for a Facebook Page: Facebook only lets a Page start a conversation with a private reply to a comment.
x?X-specific fields. Required for an X account: pass exactly one of user_id, username or comment_id. X has no messaging window, but delivers only when the contact's DM settings accept the account; otherwise the request is rejected with 422.
bluesky?Bluesky-specific fields. Required for a Bluesky account: the contact to message, by handle or DID. They receive the message and become the conversation participant.
Conversation started; the message's status shows its delivery state
application/json- response
The conversation and its first message
success*booleanconversation*A conversation with a participant
message*A message within a conversation
curl -X POST 'https://api.outstand.so/v1/conversations' \ -H 'Content-Type: application/json' \ -d '{ "social_account_id": "string", "content": "string"}'{ "success": true, "conversation": { "id": "string", "orgId": "string", "socialAccountId": "string", "network": "string", "platformConversationId": "string", "participantId": "string", "participantDisplayName": "string", "participantProfilePicture": "string", "lastMessageAt": "2019-08-24T14:15:22Z", "lastInboundAt": "2019-08-24T14:15:22Z", "unreadCount": 0, "status": "active", "metadata": { "property1": null, "property2": null }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }, "message": { "id": "string", "conversationId": "string", "platformMessageId": "string", "direction": "inbound", "source": "api", "senderId": "string", "content": "string", "mediaUrls": [ "string" ], "attachments": [ { "type": "image", "platformType": "string", "url": "string", "title": "string", "mediaId": "string" } ], "quickReplies": [ { "title": "string", "id": "string" } ], "buttons": [ { "type": "postback", "title": "string", "id": "string" } ], "interaction": { "type": "quick_reply", "id": "string" }, "story": { "type": "reply", "id": "string", "url": "string" }, "replyTo": { "messageId": "string" }, "reaction": "string", "status": "pending", "error": "string", "scheduledAt": "2019-08-24T14:15:22Z", "platformSentAt": "2019-08-24T14:15:22Z", "createdAt": "2019-08-24T14:15:22Z" }}