Enable Two-Way SMS with Cordial

In this article, we'll guide you through integrating your Cordial account to enable Two-Way SMS capabilities (Conversations) within SmarterSends. This process will involve configuring values within SmarterSends and setting up Outbound SMS Automation within Cordial. If any of the following does not make sense or you'd simply like our team to configure it for you, please reach out to our team and we'll get you setup quickly.

In this integration we'll be:

1. Create an API Key in Cordial
2. Create an SMS Automation in Cordial to be used for outbound messages
3. Create an API Key in SmarterSends to use in your Cordial Webhook
4. Create a Webhook in Cordial to receive inbound messages
5. Configure SmarterSends

Detailed Steps:

Create API Key Within Cordial

1. In the top right corner of your Cordial account you'll see your Initial which will say Settings when you hover over your initial.
2. Click your initial and select API Keys
3. Click New
4. Add the name of the API Key, "SmarterSends 2-Way SMS API"
5. Add the SmarterSends IP address to the IP whitelist: 54.146.87.194
6. Select the following permissions:
   1. Automation Templates
      1. POST /automationtemplates/{key}/send
   2. Contacts
      1. GET /contacts/{contactID}
      2. PUT /contacts{id}
7. If you are unable to select any of the above permissions, your account in Cordial may be set to Power User and not Admin. You'll need to use an Admin account to set the permissions on the API Key to the above.
8. Click Generate Key
9. Copy the API Key as we'll need it for a future step in SmarterSends.

Create a SMS Automation in Cordial

1. Now create a new SMS Automation.
2. Name your Campaign - "SmarterSends SMS - Outbound" or something descriptive.
3. Edit the content by clicking pencil icon. For the content, we are going to use a smarty along tag with your company identifier so that your customers always know who the message is from:
   SmarterSends: {$extVars.msg}
4. Decide if you want your Unsubscribe instructions included with every message. Check the "Add unsubscribe instructions checkbox if so
5. Click Save.
6. Click the Publish button.
7. Under Sending Methods, click API and then click Enable. Confirm the Sending Method by clicking Enable in the modal window.
8. Copy the message key for your SMS Automation as we'll need it in a future step.

Create an API Key in SmarterSends

1. In SmarterSends, click the Integrations link
2. Select the API integration.
3. Click Generate API Key
4. Copy the New API Key. NOTE: you will not be able to view this API Key later so be sure you store it securely. You can always Generate a new key if necessary.
5. Click Save to save your Key.

Configure SmarterSends for Two-Way SMS Conversations

1. In your SmarterSends account, select Integrations -> Two-Way SMS.
2. Select Cordial in the Two-Way SMS Provider drop-down.
3. Select the API Endpoint used for your Cordial instance or enter your custom subdomain if configured in Cordial.
4. Paste your Cordial API Key into the API Key field.
5. Paste your SMS Automation Key from the automation you created above into the Automation Key field.
6. Enter the keyword your customers will use to initiate a conversation with your SmarterSends users e.g. Service. Be sure your Default Reply mentions this keyword so your customers know how to get in touch.
7. Add/Update the Acknowledgement message text. This message is automatically sent to your customers after we receive the Service Keyword set above.
8. Enter the attribute name used for your customer's First Name e.g. first_name
9. Enter the attribute name used for your customer's Last Name e.g. last_name
10. Enter the Group Identifier attribute we will use to route conversations to the correct Group within SmarterSends. We'll assign identifiers to groups in a moment.
11. Select the Default Group if a conversation is initiated with a customer that has a Group Identifier value that does not match an assigned value or their identifier is blank.
12. Select the User Assignment Rule
    1. Oldest Recent Activity - This will assign the user (in the correct group) who has been inactive the longest, based on their most recent conversation activity helping ensure idle team members are re-engaged first.
    2. Least Active Conversations - This will assign the user (in the correct group) who is currently handling the fewest active conversations, ensuring no one is overloaded. An active conversations is one that is not Closed or marked as Spam.
    3. Longest Time Since Assignment - This will assign the user (in the correct group) who has gone the longest without being assigned a conversation. This helps ensure fair distribution and prevents the same people from receiving new conversations repeatedly.
    4. Let Users Self-Assign - New conversations remain unassigned until a team member chooses to claim them, allowing users to pick up conversations based on availability and context. This rule is not compatible with the User Isolation feature.
13. Define the number of days for your SLA (service level agreement). Conversations will be escalated if they remain awaiting a reply for this many days.
14. Define the number of days at which to send a reminder to the assigned user that the conversation is awaiting a reply.
15. Define the number of days to consider a conversation Stale e.g. awaiting a customer reply.
16. Choose to use Business/Week days or all days for the above values.
17. Save the Integration
18. Now in SmarterSends, select the Groups menu item.
19. Click the Manage Group Content Areas button
20. Add a New Content Area with a name that matches the Group Identifier Attribute you set above. Typically this would be set as a Text content area type.
21. For each Group that should be assigned Conversations, set the value for the Group Identifier content area you just created by clicking into each group and setting the value.

Create a Webhook Integration in Cordial

1. In your Cordial account, click Integrations and select Webhooks
2. Click New
3. Give the Webhook a name e.g. SmarterSends Incoming SMS and click Continue
4. Click the Pencil icon to configure the webhook
5. Leave the Webhook type as Single Request
6. Enter the Webhook URL using the subdomain of your SmarterSends instance:
   1. https://SUBDOMAIN.smartersends.com/api/cordial/webhook
7. Click the Add Header - This header ensures that only authorized messages are consumed by SmarterSends.
   1. Enter "Authorization" for the Name
   2. Enter "Bearer APIKEY" replacing APIKEY with the key you created in SmarterSends
8. Leave Rate Limiting at 100 per second.
9. Under the Trigger Events, SMS Channel Events, select Allowed events
   1. Select "crdl_incoming_sms"
10. Click Save
11. Now let's Enable the webhook by clicking Enable.
12. Cordial will walk you through sending a test event to ensure the webhook is configured correctly.
    1. In the All Events dropdown select, crdl_incoming_sms
    2. Click one of the sample events to send the test.
    3. As long as the test passes your webhook will be enabled.

Test the Integration

1. Subscribe your your short code from a SMS message
2. Send the Service Keyword e.g. Service to your short code
3. You should receive the Acknowledgement message you configured
4. In SmarterSends you should see a conversation has been created from your number.
5. Click the conversation and send a reply.
6. Ensure you receive the SMS message

That's it. You've enabled Two-Way SMS Conversations.

When a customer subscribes to your short code and receives your Default Auto Reply, they'll know to reply with your Service Keyword to initiate a conversation with your team members. Once they reply with that keyword, a conversation will be created in SmarterSends, assigned to the correct Group and user based on your settings above.