Send Your First Message

So, you've got a team set up and a user account login from requesting access, and you're ready to start using the API schema you've downloaded. Let's start by sending your first message through PivotCX.

Sending a Message requires a Conversation, which requires a Contact to converse with. Let's create those now and so you can send a message.

Add a Contact

Adding a contact requires a couple pieces of information. To start, a first and last name makes the contact easy to identify later. More importantly, since our conversations are done through SMS, PivotCX need a valid phone number (no random numbers or 123456789s), and some confirmation that we have permission to text the numbers, known as opt-in information. Notably, phone numbers must be unique across contacts (so we know how to send the SMS), so we recommend you use your personal cell phone number, and remember that once you've created a contact with it, you should not make any more contacts with that same phone number. This has the added benefit of you being able to check that you've received the message once sent.

Finally, similar to the phone number, we need an email and its opt-in information. We do not send any communication to this email but still record if the email has opted in for regulatory purposes.

Once you have a first name, last name, phone number, and email chosen, you're ready to make an API request. If you have your Postman collection imported and configured, you can make a request by adding these fields in the Body tab. You will have to slightly edit the available fields since the schema does not render the nested email and phone objects correctly. Here's an example, changing the number and address plus opt in fields to belong to their correct rows:

The above is equivalent to the following Javascript object, if you would prefer to make the request through Javascript (the configuration is similar to the Postman configuration):

{
  firstName: 'Jane',
  lastName: 'Doe',
  primaryPhone: {
    number: '+12223334444'
    optIn: true,
    optInMethod: 'list',
    optInDetail: ''     
  },
  primaryEmail: {
    address: 'example@email.com'
    optIn: true,
    optInMethod: 'delegated',
    optInDetail: ''     
  }
}

Once that request is submitted, you should have a created contact!

Add a Conversation

Good news! When you create a contact in PivotCX, it automatically starts a conversation with them - all you need to do is find the conversation that was created so you're able to message it. It should be viewable in the PivotCX chat view, but to get it from the API, you can search all the conversations for the one with your contact by the contact's name. In Postman, you can navigate to the /conversations directory and click the top-level GET request to /v1/users/{parent_lookup_user}/teams/{parent_lookup_team}/conversations/. After clicking the bulk edit button and deleting all the pre-populated query params, you can add contact_name__icontains=Jane (or whatever your chosen first or last name was) in the bulk edit screen. Then after submitting the request, you will receive all the conversations that contain that search string in their contact name (including the one you just created with your contact).

(Adding the query param in Postman this way is equivalent to appending ?contact_name__icontains=Name after your API URL).

Make note of the id in the returned conversation object, since you will use that id to form our request to send a message.

Send a Message

Success! You're ready to send a message. Head to the /conversations/{id}/send_message directory in your API collection, then in the Body tab, bulk edit and clear the default properties, and replace it with the single line message:Your message text.

Tada! You've successfully sent a message using the PivotCX API. Feel free to browse other examples.