Integration with Instant Messaging (IM) Software

Overview

CallFire provides an ability to integrate your IM client with CallFire platform, it will allow you to send short messages from any phone number to your IM channel, or reply to a sender from IM client.

This integration consists only of one Python script which sits between CallFire and IM messenger (e.g. Slack) and route an incoming message from phone number to IM channel and from IM to a phone number with help of CallFire API.

How it works under the hood:

• you type in a message in a Slack channel and hit enter, e.g. ^sms+13105551212 Hi, how are you ?
• Slack triggers an outgoing webhook and post a message to our integration app
• Integration app invokes an API to send an SMS to a particular number (e.g. 13105551212)
• Once recipient has replied CallFire triggers a webhook and post incoming message to integration app
• Once integration app has received a reply from CallFire it relays this reply to a Slack incoming webhook and text message appears in channel.

Important. This feature is experimental and you may experience some issues, in this case please send an email with description of the issue to devsupport@callfire.com.

Supported instant messengers:

• Slack

Requirements:

• Purchased number in CallFire account
• Installed Python with Bottle and Requests libraries
• Any server which may accept incoming connections
• A web server that can run Python applications (e.g. nginx and uwsgi)
• SSL certificates properly configured in your web server settings

Set up integration

This guide will show you how to set up an integration step by step and send a message to both directions: phone to IM and reply from IM to phone number.

1. Get IM integration bridge from github (it's a simple web API aplication written in Python)

   $ git clone https://github.com/CallFire/sms_slack_bridge
   

2. If you don't have a Python environment installed please do the following steps (example for OSX, for other operating systems should not be much different):

   $ brew install python
   $ pip install requests
   $ pip install bottle
   

   Now we can run Python application to make sure it works:

   cd sms_slack_bridge
   $ python sms_slack_bridge.py
   

   will print the following output:

   No slack SMS campaign found, hopefully someone will initialize it soon
   Bottle v0.12.13 server starting up (using WSGIRefServer())...
   Listening on http://localhost:8080/
   Hit Ctrl-C to quit.
   

   open http://localhost:8080/cf_slack_bridge_ping in browser, you should see

   This is the CallFire SMS to Slack bridge running on SET ME. Enjoy!
   

   Now we are ready to continue our installation
3. Create CallFire account and API credentials, how to do that see on quick start guide page.
4. Purchase a phone number (DID) from CallFire, and enable SMS on it. Read order numbers guide to know how to obtain a number through CallFire API or UI.

5. (Optional). If you have configured your web server to accept incoming connections from Internet you should skip this step, in this guide we will setup everything on localhost so we have to use some tunneling tool like ngrok to route callback requests from CallFire to our local server behind NAT. If your server has public access you don't need this step. Let's install ngrok and run it to forward all incoming connections to 8080 port

   $ brew cask install ngrok
   $ ngrok http 8080
   
   Session Status                online
   Account                       John Doe (Plan: Free)
   Version                       2.1.18
   Region                        United States (us)
   Web Interface                 http://127.0.0.1:4040
   Forwarding                    http://c9a801ba.ngrok.io -> localhost:8080
   Forwarding                    https://c9a801ba.ngrok.io -> localhost:8080
   
   Connections                   ttl     opn     rt1     rt5     p50     p90
                                 0       0       0.00    0.00    0.00    0.00
   

6. Update application settings to connect it to CallFire account.

   6.1. Open sms_slack_bridge.py script and update the next variables:

   # your application URL address
   my_url = "https://c9a801ba.ngrok.io"
   # CallFire API credentials
   cf_login = "c4545aaa777"
   cf_password = "c4545aaa777vvv22"
   # purchased phone number
   cf_did = "14242709415"
   

   6.2. Start web application to see that account is successfully connected, open http://c9a801ba.ngrok.io/cf_slack_bridge_settings

   Successfully configured for the CallFire API, webhook ID is 14239003
   You still need to configure the following variables: ['slack_send_message_url', 'slack_hook_token', 'slack_channel']
   

7. Prepare Slack channel:

   7.1. Create Slack account and log in.

   7.2. Create an "Incoming Webhook" which will post inbound text messages sent to your DID to a Slack channel.

   • Go to Slack home -> Apps & Integrations -> Manage -> Custom Integrations -> Incoming Webhooks -> Add Configuration.
   • Select Slack channel (e.g. #callfire-integration, create a new channel if needed)
   • Copy webhook URL and set it as value for the slack_send_message_url variable
   • Add a description label of the webhook and icon if needed

   7.3. Create an "Outgoing Webhook". Outgoing webhook will invoke CallFire API to send a text message from your Slack channel.

   • Go to Slack home -> Apps & Integrations -> Manage -> Custom Integrations -> Outgoing Webhooks -> Add Configuration.
   • Select source channel for outgoing messages, should be the same that you used in previous steps.
   • Set trigger word: e.g. ^sms+1.
   • Set the URL to listen outgoing messages from Slack: https://c9a801ba.ngrok.io/from_slack (change the URL address to yours)
   • Take the webhook token and save it into slack_hook_token variable inside sms_slack_bridge.py application.
   • Add a description label of the webhook and icon if needed.
   • Set slack_channel variable to the name of the channel used for integration.

Setup is completed.

Application configuration should look like:

# your application URL address
my_url = "https://c9a801ba.ngrok.io"
# CallFire API credentials
cf_login = "c4545aaa777"
cf_password = "c4545aaa777vvv22"
# purchased phone number
cf_did = "14242709415"

## slack URL used to post messages to your channel, security token, and channel name
slack_send_message_url = "https://hooks.slack.com/services/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"
slack_hook_token = "duHYZqh5efwbktVUNXfyU77K"
slack_channel = "#callfire-integration"

Let's go to http://c9a801ba.ngrok.io/cf_slack_bridge_settings to see everything is up and running:

CallFire Slack bridge running on https://c9a801ba.ngrok.io

Successfully configured for the CallFire API, webhook ID is 14559003
All variables for the Slack interface are set.

That's all! Now you can start conversation by sending a message from IM channel to phone or vice versa.

How to send a message from your phone to Slack and vice verse

1. Phone -> Slack: send an SMS message to a purchased DID, it will automatically appear in your Slack channel.
2. Slack -> Phone: send a message in following format: ^sms+1<10_digit_phone_number> <message_text>, example:

^sms+13105551212 thank you for contacting us

Limitations

• private 1-on-1 isn't supported

Found an issue ?

If you found any issues please contact us devsupport@callfire.com.