In App Messaging REST Service

In App Messaging is a RESTful web service that allows two-way, asynchronous communication (messaging) between third party applications and Agents on the ContactAtOnce! Network. It enables App to App Asynchronous Message Communication. No SMS or Phone Number required on either side.

Consumer perception is that messaging is fully incorporated into Publisher app.

Since the API is based on REST principles, it’s very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API. The ContactAtOnce! In App Messaging REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

In App Messaging uses Basic Authentication. ContactAtOnce! can issue you an APIKEY to use. A username and password are not necessary.

In App Messaging Resources

Start
SendMessage
GetConversations
ConversationGetTranscript
SetMessageStatus

Publisher Endpoints

ReceiveMessage from CAO
ReceiveMessageStatus from CAO

Base URL (regionally defined):

North America : https://api.contactatonce.com/
Australia : https://api.contactatonce.com.au/
Europe : https://api.contactatonce.co.uk/

System Diagram
MessagingSystemDiagram

Start

Starts a Messaging Conversation with specified ConsumerId

Method: POST 
/api/v1.0/AsyncConversation/Start

Request
Parameter	Type	Required	Description
AdvertiserId	String	Required	Unique ID assigned to Advertiser Account by Publisher at provisioning.
ConsumerId	String	Required	Unique ID assigned to Consumer by Publisher.
SessionId	String	Required	Unique Id assigned to the Conversation by the Publisher. If provided, it will be returned in Messages posted by ContactAtOnce! to the inbound message URL.
ExternalMessageId	String	Required	Unique ID assigned to the Message by Publisher
Message	String	Required	Body of message to be sent
Device	String	Optional	Mobile Device of the Consumer
OSVersion	String	Optional	Mobile Operating System of the Consumer's Mobile Device
ConsumerFirstName	String	Optional	First Name of Consumer
ConsumerLastName	String	Optional	Last Name of Consumer
ConsumerPhoneNumber	String	Optional	Mobile Number of Consumer
ListingDetails	String	Optional	Free form contextual information to be associated with the Conversation. Typically name/value pairs with a special (ÿ) separator character.

Response
Paremeter	Type	Description
VisitId	Int	Unique Id assigned to the Conversation by ContactAtOnce!
ConsumerId	String	Unique ID assigned to Consumer by Publisher.
SessionId	String	Unique Id assigned to the Conversation by Publisher
Status	Int	Result of the Post. 0 = Success 1 = Failure If 1, a FailureDescription will also be provided.
FailureDescription	String	Description of failure used for debugging purposes

Sample Header- JSON

Authorization: Basic {YOUR_API_KEY}
Accept: version=2;

Sample POST – JSON

{
   "AdvertiserId":"12345",
   "ConsumerId":"12345",
   "SessionId":"abc1234",
   "ExternalMessageId":"5236987",
   "Message":"Do you offer special financing on this vehicle",
   "Device":"iPhone 6+",
   "OSVersion":"1.0",
   "ConsumerFirstName":"Bob",
   "ConsumerLastName":"Johnson",
   "ConsumerPhoneNumber":"14045551212",
   "ListingDetails":"year=2014ÿmake=Fordÿmodel=F150"
}

Sample Response- JSON
If the POST is successful, the value for Status will be 0 and a VisitId will be assigned to the Conversation and returned along with ConsumerId and SessionId if provided. If the POST is not successful, the values for Status will be 1 and a description of the failure will be provided.

{
  "VisitId": 5125890558,
  "ConsumerId": "12345",
  "SessionId": "abc1234",
  "Status": 0,
  "FailureDescription": ""
}

Back to Top

SendMessage

Sends a message to a specified Consumer.

Method: POST 
/api/v1.0/AsyncConversation/SendMessage

Resource Properties

Request
Parameter	Type	Required	Description
VisitId	Int	Required	Unique identifier for the Message Conversation
MessageId	String	Required	Unique ID assigned to the Message by ContactAtOnce
ExternalMessageId	String	Required	Unique ID assigned to the Message by Publisher
Message	String	Required	Body of the message to be sent
SessionId	String	Required	Unique Id assigned to the Conversation by Publisher. If provided, will be returned in Messages posted by ContactAtOnce! to inbound message URL.

Response
Paremeter	Type	Description
VisitId	Int	Unique Id assigned to the Conversation by ContactAtOnce!
ConsumerId	String	Unique ID assigned to Consumer by Publisher.
SessionId	String	Unique Id assigned to the Conversation by Publisher
Status	Int	Result of the Post. 0 = Success 1 = Failure If 1, a FailureDescription will also be provided.
FailureDescription	String	Description of failure used for debugging purposes

Sample Header- JSON

Authorization: Basic {YOUR_API_KEY}
Accept: version=2;

Sample POST – JSON

{
    "VisitId":5125890558,
    "MessageId":"52369887",
    "ExternalMessageId":"5236987",
    "Message":"Do you any 3 bedroom apartments on the first floor in Bldg 3?", 
    "SessionId":"abc1234"
 }

Sample Response- JSON
If the POST is successful, the value for Status will be 0 and the VisitId, ConsumerId & SessionId will be returned. If the POST is not successful, the values for Status will be 1 and a description of the failure will be provided.

{
  "VisitId": 54150558,
  "ConsumerId": "12345",
  "SessionId": null,
  "Status": 0,
  "FailureDescription": ""
}

Back to Top

GetConversations

Returns a list of Message Conversations with the specified Consumer.

Method: GET
/api/v1.0/AsyncConversation/GetConversations/{ConsumerID}

Request
Parameter	Type	Required	Description
ConsumerId	String	Required	Unique identifier for the Consumer

Response
Paremeter	Type	Description
Conversations	Array of AsyncConversationItem	All messages exchanged between consumer and business
ConsumerId	String	Unique ID assigned to Consumer by Publisher.
Status	Int	Result of the Post. 0 = Success 1 = Failure If 1, a FailureDescription will also be provided.
FailureDescription	String	Description of failure used for debugging purposes

Sample Header- JSON

Authorization: Basic {YOUR_API_KEY}
Accept: version=2;

Sample Response – JSON

{
    "Conversations": [
        {
            "AdvertiserId": "Marc",
            "AdvertiserName": "Nalley Lexus",
            "AgentName": "Jesse James",
            "SessionId": "abc123",
            "VisitId": "12272283",
            "LastMessageDateTime": "6/15/2015 4:13 PM",
            "LastMessage": "see you at 4:00",
            "Status": "0"
        }
    ],
    "Status": 0,
    "FailureDescription": null
}

Back to Top

GetTranscript

Returns the complete transcript of a specified Message Conversation.

Method: GET
/api/v1.0/AsyncConversation/GetTranscript/{VisitId)

Request
Parameter	Type	Required	Description
VisitId	Int	Required	Unique Id for the Conversation assigned by ContactAtOnce! at the time of original POST to AsyncMessageConversation

Response
Paremeter	Type	Description
Message	Array of AsynConversationMessage	All messages during the conversation
NumMessages	Int	Total number of messages exchanged during conversation
TotalUnreadConsumerMessages	Int	Total number of messages that have not been read by an agent
VisitId	Int	Unique Id assigned to the Conversation by ContactAtOnce!
ConsumerId	String	Unique ID assigned to Consumer by Publisher.
SessionId	String	Unique Id assigned to the Conversation by Publisher
Status	Int	Result of the Post. 0 = Success 1 = Failure If 1, a FailureDescription will also be provided.
FailureDescription	String	Description of failure used for debugging purposes

Authorization: Basic {YOUR_API_KEY}
Accept: version=2;

Sample Response- JSON

{
    "Messages": [
        {
            "TimeStamp": "6/12/2015 10:58 PM",
            "SpeakerName": "Joe Lewis",
            "SpeakerRole": "Agent",
            "Message": "Do you like ice cream?",
            "MediaURL": ""
        },
        {
            "TimeStamp": "6/12/2015 10:59 PM",
            "SpeakerName": "Customer",
            "SpeakerRole": "Customer",
            "Message": "Yes",
            "MediaURL": ""
        },
        {
            "TimeStamp": "6/15/2015 4:13 PM",
            "SpeakerName": "Joe Lewis",
            "SpeakerRole": "Agent",
            "Message": "What is your favorite flavor?",
            "MediaURL": ""
        }
    ],
    "VisitId": 12272283,
    "ConsumerId": "1234",
    "SessionId": "abc123",
    "Status": 0,
    "FailureDescription": null
}

Back to Top

MessageStatus

The Publisher, optionally, may host a secure REST resource to receive read and delivered receipts from CAO. Message from CAO will be Application/JSON encoded HTTPS POST to
the Publisher Specified Endpoint.

Method: POST
The Publishers Specified Endpoint

Request
Parameter	Type	Required	Description
VisitId	Int	Required	Unique identifier for the Message Conversation
MessageId	String	Required	Unique ID assigned to the Message by ContactAtOnce
ExternalMessageId	String	Required	Unique ID assigned to the Message by Publisher
MessageStatus	String	Required	Status of the message 0 - Unknown 1 - Delivered 2 - Read
SessionId	String	Required	Unique Id assigned to the Conversation by Publisher. If provided, will be returned in Messages posted by ContactAtOnce! to inbound message URL.

Response
Paremeter	Type	Description
Status	Int	Result of the Post. 0 = Success 1 = Failure If 1, a FailureDescription will also be provided.
FailureDescription	String	Description of failure used for debugging purposes

Sample Header- JSON

Authorization: Basic {YOUR_API_KEY}
Accept: version=2;

Sample POST – JSON

{
 "VisitId":"12272283",
 "ExternalMessageId":"293938293",
 "MessageId":"292020303",
 "MessageStatus":"2",
 "SessionId":"abc123"
}

Sample Response- JSON

{
 "Status": 0,
 "FailureDescription": null
}

Back to Top

Publisher Endpoints

ReceiveMessage

The Publisher is required to host a secure REST resource to receive messages from CAO. Message from CAO will be Application/JSON encoded HTTPS POST to the Publisher
Specified Endpoint.

Method: POST
The Publishers Specified Endpoint

Request
Parameter	Type	Required	Description
VisitId	Int	Required	Unique identifier for the Message Conversation
SessionId	Int	Required	Unique ID assigned to the Session
ConsumerId	Int	Required	Unique ID assigned to the consumer
DateTime	DateTime	Required	Date and Time of the message in the Conversation
MessageId	Int	Required	Unique ID assigned to the Message by ContactAtOnce
Message	String	Required	Body of the message
MediaURL	String	Optional	URL to any media that may have been included in the conversation
AgentName	String	Required	Name of the Agent who answered the conversation
AgentImageUrl	String	Required	The URL to the agent's image

Sample Header- JSON

Authorization: Basic {YOUR_API_KEY}
Accept: version=2;

Sample Message POST to Publisher Endpoint – JSON

{
"VisitId":"12617187",
"SessionId":"abc123456",
"ConsumerId":"128740954930930",
"DateTime":"2015-01-01T00:00:00 ",
"MessageId":"12345678",
"Message":"that was a long message",
"MediaURL":"https://media.cao.com/images/sbc.png"
"AgentName":"Sally Salesperson"
"AgentImageURL":"https://media.cao.com/images/sally.png"
}

Back to Top

Receive Read/Delivery Receipt

Method: POST
The Publishers Specified Endpoint

Request
Parameter	Type	Required	Description
VisitId	Int	Required	Unique Id assigned to the Conversation by ContactAtOnce!
ExternalMessageId	String	Required	Unique ID assigned to the Message by Publisher
SessionId	Int	Required	Unique ID assigned to the Session by the Publisher
ConsumerId	Int	Required	Unique ID assigned to the Consumer by the Publisher
MessageId	Int	Required	Unique ID assigned to the Message by ContactAtOnce
MessageStatus	String	Required	Status of the message 0 - Unknown 1 - Delivered 2 - Read

Sample Header- JSON

Authorization: Basic {YOUR_API_KEY}
Accept: version=2;

Sample POST – JSON

{
"VisitId":"12617187",
"SessionId":"abc123456"
"ConsumerId":"128740954930930",
"ExternalMessageId":"29393892",
"MessageId":"987654322",
"MessageStatus":"2"
}

Back to Top