setUpConversation¶

Request Method: POST

Description: Function which set up a conversation between the origin and destination party through a conversational VoxNumber.

URL: https://api.iovox.com:444/Conversations?v=3&method=setUpConversation

The following parameters can be sent in the querystring

Parameter	Description	Default Value	Data Type	Mandatory
v	API version to use		INTEGER	YES

Payload¶

The following XML payload must be sent with a setUpConversation request:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <country>United Kingdom</country>
    <origin_contact>
        <contact_id>CO1</contact_id>
        <first_name>John</first_name>
        <last_name>Smith</last_name>
        <business_phone>44772345443323</business_phone>
        <country>United Kingdom</country>
        <email>john.smith@iovox.com</email>
    </origin_contact>
    <link_id>AD-123</link_id>
    <expiration>
        <value>2</value>
        <unit>MONTH</unit>
    </expiration>
    <conversation_details>
        <sendSms>
            <origin>44772345443323</origin>
            <welcome_destination_message>You have an enquiry for AD-123</welcome_destination_message>
            <welcome_origin_message>Thanks for your interest for AD-123</welcome_origin_message>
            <main_message>Hello I am in love with this car. Is it still available?</main_message>
        </sendSms>
    </conversation_details>
</request>

Payload Description¶

Node Name	Description	Default Value	Data Type	Mandatory
country	A valid country name.		STRING	YES
origin_contact	Contains all the origin contact information needed			YES
origin_contact>contact_id	The reference to the origin contact.		STRING	NO
origin_contact>first_name	The first name of the origin contact		STRING	YES
origin_contact>last_name	The last name of the origin contact		STRING	YES
origin_contact>business_phone	With the origin phone number in an internationalised format		STRING	YES
origin_contact>country	With the country of the origin contact		STRING	NO
origin_contact>email	With the email address of the origin contact		STRING	NO
link_id	With the reference to the link we want to set up the conversation		STRING	YES, unless the destination_contact is set
destination_contact	Contains all the destination contact information needed			NO, unless Link ID is not set
destination_contact>contact_id	The reference to the destination contact.		STRING	NO
destination_contact>first_name	The first name of the destination contact.		STRING	YES
destination_contact>last_name	The last name of the destination contact		STRING	YES
destination_contact>business_phone	With the destination phone number in an internationalised format		STRING	YES
destination_contact>country	With the country of the destination contact		STRING	NO
destination_contact>email	With the email address of the destination contact		STRING	NO
conversation_details>sendSms>destination	Destination phone number for the sendSms event. This phone number should belong to the origin contact phone number.		STRING	YES, It is only required if the destination contact is set in the XML
conversation_details>sendSms>welcome_message	Common message which will be sent when the conversation is set up. This will be sent to the origin and destination.		STRING	NO
conversation_details>sendSms>welcome_origin_message	Message which will be sent to the origin party when the conversation is set up.		STRING	NO
conversation_details>sendSms>welcome_destination_message	Message which will be sent to the destination party when the conversation is set up.		STRING	NO
conversation_details>sendSms>main_message	Message which contains the text sent from the origin to the destination.		STRING	YES

Result¶

Error Result¶

HTTP Code	Error String	Resolution
400	API Version Empty	Add a value for the v parameter in the query string
400	API Version Invalid	Correct v parameter
400	Request Method must be POST. x attempted	Switch request method x to POST
400	XML Empty	Add xml to the request body
400	XML parse error. x at line y, column z	Correct XML at point x on line y, column z
400	Request Empty	Add the conversation details for the request
400	Country Empty	Add country.
400	Country does not exist	Correct for a valid country.
400	Origin Contact Empty	Add origin_contact.
400	Link ID Empty	Add a link_id.
400	Link ID does not exists	Correct the link_id.
400	Link ID does not have an SMS Template attached	Attach an SMS template to the link.
400	Link ID does not have a forwarding contact	Attach a contact to the SMS template attached to the link.
400	Origin Contact Empty	Add origin_contact details
400	Origin Contact First Name empty	Add first_name for the origin contact
400	Origin Contact First Name invalid	Correct first_name for the origin contact
400	Origin Contact Last Name empty	Add last_name for the origin contact
400	Origin Contact Last Name invalid	Correct last_name for the origin contact
400	Origin Contact Email is not valid email address	Correct the email address for the origin contact
400	Origin Contact Business Phone invalid	Correct the business phone number for the origin contact
400	Origin Contact Business Phone is not internationalised	Correct the business phone number is not in international format.
400	Destination Contact First Name empty	Add first_name for the destination contact
400	Destination Contact First Name invalid	Correct first_name for the destination contact
400	Destination Contact Last Name empty	Add last_name for the destination contact
400	Destination Contact Last Name invalid	Correct last_name for the destination contact
400	Destination Contact Email is not valid email address	Correct the email address for the destination contact
400	Destination Contact Business Phone invalid	Correct the business phone number for the destination contact
400	Destination Contact Business Phone is not internationalised	Correct the business phone number is not in international format.
400	Conversation Details Empty	Add conversation_details
400	Conversation Details x of y Origin empty	Add origin in the conversation
400	Conversation Details x of y Origin should belong to origin contact	Add origin which belongs to the phone numbers of the destination contact
400	Conversation Details x of y Origin cannot be the same than destination	Correct either origin or destination phone number
400	Conversation Details x of y Destination empty	Add destination in the conversation
400	Conversation Details x of y Destination should belong to destination contact	Add destination which belongs to the phone numbers of destination contact
400	Conversation Details x of y Main message is empty	Add the main_message in the conversation
400	Conversation Details x of y Main message must be less than 160 characters	Correct the main_message in the conversation
400	Conversation Details x of y Welcome message must be less than 160 characters	Correct the welcome_message in the conversation
400	Conversation Details x of y Welcome message origin must be less than 160 characters	Correct the welcome_message_origin in the conversation
400	Conversation Details x of y Welcome message destination must be less than 160 characters	Correct the welcome_message_destination in the conversation
500	Internal Server Error	Retry later

Success Result¶

HTTP/1.1 201 Created

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <voxnumber>447441913709</voxnumber>
    <conversation_id>09330234-dc1a-11e6-9852-d43d7ed6ce4c</conversation_id>
</response>