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_id and instagram.author_id (both required) to send a private reply to the comment's author. Use accountId, commentId and authorId from the comment.received webhook as social_account_id, instagram.comment_id and instagram.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/messages is rejected with 422. Add instagram.quick_replies or instagram.buttons to 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.

POST
/v1/conversations

Request Body

application/json
  1. body

Send the first message to a contact, starting a conversation with them

social_account_id*string

The connected account to send from. To reply to a comment, the account that owns the post (accountId in the comment.received webhook).

Length1 <= length
content*string

Text body of the first message. Media is not supported when starting a conversation.

Length1 <= length
instagram?

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.

Response Body

Conversation started; the message's status shows its delivery state

application/json
  1. response

The conversation and its first message

success*boolean
conversation*

A conversation with a participant

message*

A message within a conversation

Example Request
curl -X POST 'https://api.outstand.so/v1/conversations' \  -H 'Content-Type: application/json' \  -d '{  "social_account_id": "string",  "content": "string"}'
Example Response
{  "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"  }}