set-up.md 9.68 KB
Newer Older
1
# Set-up
2
3

In this chapter, the steps required to set up an SMS gateway will be
4
explored. Once configured, you will be able to send both single and mass text messages to
Justin Freeman's avatar
Justin Freeman committed
5
individual contacts which have a **mobile phone number** defined, ie. **Phone Type** must be "Mobile".
6
7

**Note**: Contacts which do not have a mobile phone number defined **will not** receive a SMS text message.
8

9
## Configuring a Clickatell SMS Gateway
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

### Registering for a Clickatell account

The Clickatell service is an online SMS gateway designed for the sending
of text messages via the Internet. They offer several products, but here
we are only interested in the "Developer's Central" SMS gateway, as it
offers more advanced tools needed to link it to CiviCRM (this is
achieved through APIs; see the CiviCRM developer guide for more
information). Registering for a Clickatell account is free, and they
supply 10 complimentary credits to try the service. To sign up, visit:

[http://www.clickatell.com/register/](http://www.clickatell.com/register/)

Once you have registered for a Developer's Central account, please
sign-in and follow the steps below (when logging in you must select
"Central API" as the product and enter your Client ID):

27
1.
28
In the Central Home dashboard, click "Create a new Connection" under
29
"Connection Status" (New language is "Get another API". Page looks also changed.)
30

homotechsual's avatar
homotechsual committed
31
![Clickatell settings screen](../img/clickatell-settings.png)
32
33

1.
gah242s's avatar
gah242s committed
34
Select "HTTP/S" as the connection type (New language: HTTP API)
35

36
1.
37
38
Four optional settings will appear, including:
    -   Description: change the name of the connection (e.g. "CiviCRM HTTP")
39
    -   Replace leading zero: enable this option if mobile phone numbers against
40
41
        your contacts begin with "0". For delivery to be successful, all
        numbers must begin with the country code if this is not enabled.
gah242s's avatar
gah242s committed
42
        (This option no longer exists.)
43
44
45
46
    -   Enable IP Address Restriction: if you know the IP address of your
        CiviCRM server, you can enter it here to ensure that text messages
        cannot be sent using your account elsewhere (your username and
        password would be needed to do this)
gah242s's avatar
gah242s committed
47
48
49
50
        (New language:  "Protect your account from fraud by restricting IP addresses")
    -   Enable your app to receive message delivery notifications (New option?)
        Enter the correct URL for your site. Example:
        Drupal: http://www.example.com/civicrm/sms/callback?provider=org.civicrm.sms.clickatell
51
        WordPress: https://www.example.org/?page=CiviCRM&q=civicrm%2Fsms%2Fcallback&provider=org.civicrm.sms.clickatell
gah242s's avatar
gah242s committed
52
53


54

55
1.
56
Click "Submit and Get API ID" to generate an API ID, and on the next
57
page, make a note of it.
58
59
60
61
62

### Completing the SMS Provider settings in CiviCRM

You now have all of the information needed to configure SMS in CiviCRM.
To continue, return to CiviCRM and go to: **Administer** > **System
63
Settings**> **SMS Providers**. Click "Add New Provider".
64

homotechsual's avatar
homotechsual committed
65
![image](../img/CiviCRM_SMS_adding-a-provider.png)
66
67
68
69
70
71
72
73
74
75
76

Complete the following settings:

-   Name: select "Clickatell"
-   Title: give the SMS provider a title user's will see (e.g.
    "Clickatell SMS")
-   Username: enter your Clickatell username
-   Password: and your Clickatell password
-   API type: select "http"
-   API URL: type the URL as follows: https://api.clickatell.com
-   API Parameters: this is where you should provide your API ID. The
77
    format required is: `api_id=8473658`
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
-   Is this provider active?: tick to enable the SMS gateway
-   Is this a default provider?: check this option to make it the
    default, where multiple SMS providers are available

CiviCRM will now be configured to send text messages to your contacts.

### Testing the SMS gateway

You can begin testing the gateway using the methods laid out in the
chapter "Everyday tasks". However, please note that if you are using the
10 complimentary SMS credits which came with the account, until you have
purchased credits Clickatell will replace the content with thank you
text like the message below:

```
Thanks for testing Clickatell's gateway coverage. You will be able to change the content of your message after your initial purchase of message credits.
```
gah242s's avatar
gah242s committed
95

96
### After upgrading your Clickatell account to a paid account
gah242s's avatar
gah242s committed
97

98
Once you have upgraded your Clickatell account, you will need to change a
gah242s's avatar
gah242s committed
99
few parameters to get things working again.
100
101
In CiviCRM,  go to: **Administer** > **System Settings**>
**SMS Providers** and click Edit on your "Clickatell" provider. In the API
gah242s's avatar
gah242s committed
102
Parameters box, under the api_id line, add a from= and a mo=1 parameter.  The
103
from= number is the mobile phone number associated with the api_id in your Clickatell
gah242s's avatar
gah242s committed
104
105
106
107
108
109
110
111
112
113
account.

Your API parameters should now look like:
```
api_id=8473658
from=15551234567
mo=1
```

Back in your ClickATell Developer's Central page, click on the America's 2 Way SMS
114
tab, then click Manage next to the mobile phone number you are working with.  For the
gah242s's avatar
gah242s committed
115
116
117
Primary Callback:  Reply Path, choose "HTTP Get" from the dropdown.  In the target
address, enter the same address as used before:
Drupal: http://www.example.com/civicrm/sms/callback?provider=org.civicrm.sms.clickatell
118
WordPress: https://www.example.org/?page=CiviCRM&q=civicrm%2Fsms%2Fcallback&provider=org.civicrm.sms.clickatell
119
120
121
122
123
124
125
126
127
128
129
130
131
132

## Configuring a Twilio SMS Gateway

### Registering for a Twilio account

Twilio offer a wide range of communications and telephony services in
most countries. CiviSMS uses the "Programmable SMS" feature. You can
register a free trial account, which will allow you to test the service.

To sign up, visit:

[https://www.twilio.com/try-twilio](https://www.twilio.com/try-twilio)

Once you have registered for an account, you will be asked to verify
133
your account phone number via SMS or call. You will then be taken to the Console.
134

135
### Getting a mobile phone number
136

137
Your trial account entitles you to a free rented Twilio mobile phone number,
138
which you can use to send SMS. However, free accounts must verify
139
140
a mobile phone number before it can receive SMS. For the purposes of this
guide, we will send a message to the same mobile phone number you verified
141
142
143
in the registration step.

1. From the [Console homepage](https://www.twilio.com/console), click the
Sean Madsen's avatar
Sean Madsen committed
144
**Programmable SMS** product.
145

homotechsual's avatar
homotechsual committed
146
![Programmable SMS](../img/twilio-programmable-sms.png)
147

Sean Madsen's avatar
Sean Madsen committed
148
2. Click the red **Get Started** button.
149

150
3. Click the **Get a number** button, near the top of the page. A mobile phone
151
152
number will be suggested to you. If the country of the number is
not accurate, use "Search for a different number". Otherwise, click
Sean Madsen's avatar
Sean Madsen committed
153
**Choose this number**, and **Done**, after noting down the number.
154

155
You now have a rented mobile phone number that can send and receive SMS messages.
156

157
### Setting up your new mobile phone number in Twilio
158

Sean Madsen's avatar
Sean Madsen committed
159
1. Click the **All Products & Services** icon, in the far left navigation bar.
160
161
162
163
164
165
166
167

2. Choose "Phone Numbers".

3. Click your new number from the list to set it up.

4. Under the "Messaging" section, change the "A message comes in webhook" to the
following, replacing example.com with your CiviCRM installation.

168
For Drupal, use `https://example.com/civicrm/sms/callback?provider=org.civicrm.sms.twilio`
169

170
For WordPress, use `https://example.com/civicrm?civiwp=CiviCRM&q=civicrm%2Fsms%2Fcallback&provider=org.civicrm.sms.twilio`
171
172
173

This will send any replies that your messages receive back to CiviCRM.

homotechsual's avatar
homotechsual committed
174
![Messaging](../img/twilio-number-callback.png)
175
176
177
178
179
180
181
182
183
184
185
186
187

5. Click "Save".

### Getting your Twilio provider settings

1. In the Twilio Console, go back to the [Console homepage](https://www.twilio.com/console).

2. Copy down your "Account SID" and "Auth Token" (you will need to click the token to reveal it).

You now have all of the information needed to configure SMS in CiviCRM.

### Setting up your new SMS Provider in CiviCRM

188
Now that you have a Twilio account with a mobile phone number, it needs to be set up in CiviCRM.
189
190

1. Go to CiviCRM and go to: **Administer** > **System
Sean Madsen's avatar
Sean Madsen committed
191
Settings**> **SMS Providers**. Click **Add New Provider**.
192

homotechsual's avatar
homotechsual committed
193
![image](../img/CiviCRM_SMS_adding-a-provider-twilio.png)
194
195
196

2. Set up the provider as follows:

Sean Madsen's avatar
Sean Madsen committed
197
198
199
200
201
202
    * Name: select "Twilio"
    * Title: give the SMS provider a title user's will see (e.g. "Twilio SMS")
    * Username: enter your "Account SID" from the previous step
    * Password: enter your "Auth Token" from the previous step
    * API type: leave as "http"
    * API URL: leave as "https://api.twilio.com/"
203
    * API Parameters: enter "From=" followed by your Twilio mobile phone number from the
Sean Madsen's avatar
Sean Madsen committed
204
    previous step, in international format with no spaces. On a second line, enter "mo=1".
205
206
207
208
209
210
211
212
213
214
    
    !!! note
        Twilio will only allow you to send around 200 messages per day from 
        each long number. If you want to send more messages per day and you 
        cannot afford a short code, you can get additional long numbers from 
        Twilio. Include those additional numbers by listing them, separated by 
        a `|` (the "pipe" character). For example: 
        `From=12345051212|19875052323|15675052345`. When you include multiple
         long numbers, one number is chosen at random each time an SMS message 
         is sent.
Sean Madsen's avatar
Sean Madsen committed
215
216

3. Click Save to create your provider.
217
218
219

### Testing CiviSMS

220
You can now use CiviSMS to send an SMS message to any mobile phone number you have access too.
221

homotechsual's avatar
homotechsual committed
222
See [Everyday Tasks](everyday-tasks.md) for some ways you can send messages.
223
224
225
226
227
228
229
230
231
232

If you reply to an SMS message, it will be created as an activity on your CiviCRM record.

### Upgrading Twilio

To properly use Twilio as an SMS gateway, you will need a paid account.

You can upgrade your account to a full account by clicking "Upgrade" in
the top right corner from the Twilio console.

233
Once you have upgraded, your rented mobile phone number will be available for full use,
234
235
and charged against your Twilio credit. 

236
You will now be able to send SMS to any mobile phone number.