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.
POST/v1/conversations

Request Body

social_account_idstring

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
contentstring

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

Length1 <= length
instagram?object

Instagram-specific fields. Required for an Instagram account: Instagram only lets a business start a conversation with a private reply to a comment.

Response Body

const body = JSON.stringify({  "social_account_id": "x8Kp2",  "content": "Thanks for your comment! Here is the link you asked for."})fetch("https://api.outstand.so/v1/conversations", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})
{
  "success": true,
  "conversation": {
    "id": "9dyJS",
    "orgId": "string",
    "socialAccountId": "string",
    "network": "instagram",
    "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": "3kPqR",
    "conversationId": "string",
    "platformMessageId": "string",
    "direction": "inbound",
    "source": "api",
    "senderId": "string",
    "content": "string",
    "mediaUrls": [
      "string"
    ],
    "status": "pending",
    "error": "string",
    "scheduledAt": "2019-08-24T14:15:22Z",
    "platformSentAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z"
  }
}
{
  "success": false,
  "error": "Conversation not found"
}
{
  "success": false,
  "error": "Conversation not found"
}
{
  "success": false,
  "error": "Conversation not found"
}
{
  "success": false,
  "error": "Conversation not found"
}
{
  "success": false,
  "error": "Internal server error"
}
{
  "success": false,
  "error": "Conversation not found"
}