This manual is intended for anyone who wants to send and/or receive SMS'es from their WordPress-installation, and who has administrative privileges over the installation.

When you create an account with GatewayAPI.com, you'll instantly be able to send and receive text messages in more than 200 countries of the world. It requires however, that you provide a service of some sort for sending SMS'es to GatewayAPI.com, and perhaps another for receiving SMS'es as well.

This usually requires a programmer though, which can be a turn-off for many. That's why we have created a plugin for WordPress, one of the most popular CMS'es on the internet, in order to deliver a ready-made solution, that integrates easily into any WordPress-based website.

Our WordPress-plugin currently features:

Backend:

• Use WordPress admin to manage and send – or do it all from PHP.
• Manage and group recipients.
• Send to single recipients or groups.
• Change sender text, type of SMS – completely unbranded SMS’es.
• Dynamically use meta-data within your SMS’es.
• Track the delivery status of an SMS.
• Automatic synchronization of recipients and WordPress users, including selected metadata.
• Add unlimited meta fields to your recipients: 11 content types to pick from!

Receive SMS’es:

• Receive SMS’es sent from the phones of your visitors and others.
• View received messages from the backend, via the “SMS Inbox”.
• Handle incoming SMS’es from WordPress-hooks (for programmers).
• Create automated replies based on incoming text.

Integration in your website:

• Short-code generator, creating sign up, update and unsubscribe forms.
• Public forms feature CAPTCHA and two-factor flows.
• Custom security? Create a “Send SMS” form via a shortcode.

SMS gateway:

It is all backed by our in-house developed high quality, low price EU-based SMS-gateway:

• GatewayAPI.com has sent 180+ million SMS’es.
• We regularly send over 1.500 SMS’es per second.
• Headquarters in Copenhagen, Denmark.
• Company founded in 1999.
• Free support, no subscription AND unbeatable prices.
• Most SMS’es are delivered within 0,3 second.

To get started you need to already have a WordPress installation up and running. The installation must be up-to-date and should be kept up-to-date.

Furthermore you need administrator privileges to install and configure the plugin, though you can get by as an editor for most day-to-day tasks.

You must also create an account with GatewayAPI.com, but that part is documented below.

In order to also receive incoming SMS'es in your WordPress-installation, your installation needs to be online and publicly available. Ie. the URL of your site must be accessible from the rest of the world. This is due to the fact, that when an SMS is received on your behalf by GatewayAPI.com, is it delivered to you by GatewayAPI.com connecting to your WordPress-installation, which is only possible when the installation is online.

To summarize, this is what is required:

• A functional WordPress-installation.
• Administrator privileges (for installation and configuration).
• At least editor privileges (for day to day tasks).
• For receiving SMS'es: A publicly available WordPress installation.
• A GatewayAPI.com account (documented below)

1. Go to "Plugins" » "Add new". If this feature is not available to you, then you do not have administrative privileges, which is a requirement.
2. In the search field at the top right, type "GatewayAPI". The plugin should appear.
3. Install and activate the plugin.

Once you have installed and activated the plugin, then go to the GatewayAPI Settings page:

1. Go to "Settings" » "GatewayAPI Settings".

2. On this page you will be asked for GatewayAPI.com access credentials. Creating an account should be fairly self-explainatory if you just visit GatewayAPI.com.
3. When you have created the account, then while still on GatewayAPI.com, access the dashboard and go to "Settings" » "API Keys".
4. Access credentials has been created automatically for you, so on this page, all you have to do is click the "Key"-icon next to the first row on the page labeled "Automatically created by the system".

5. Copy the "Key" from GatewayAPI.com into "OAuth Key" in your WordPress-installation. The same goes for "Secret" which must be copied to "OAuth Secret".

6. Finally, we would highly recommend enabling the checkbox "Enable sending UI". All of the following sections assumes that you have enabled this feature!

To create a recipient from the backend, simply go to "SMS'es" » "Create recipient". You must fill out at least the Country Code and the Phone number field. We recommend that you also fill in the "Name" field for easy reference.

Note: Each recipient must contain a unique phone number, ie. you cannot have the same person created multiple times.

When done, click Publish.

All recipients should be added to at least one group. This way you can easily send SMS'es to everyone, if they are all a part of the same group, or you can send to a subselection of the recipients in your system. You may create as many groups as you like.

You can create a new group in two ways:

1. When on the Create/Edit-screen for a recipient, there's a box at the right side, called "Recipient groups". Simply click "Add new recipient group" to create a new group.

2. By clicking "SMS'es" » "Groups" and fill in the form to the left.

By default the plugin supports adding a name, a country code, a phone number and select groups. This is oftentimes not enough. It is therefore possible to add more custom fields to the recipients.

In order to add a new recipient field:

1. Go to "Settings" » "GatewayAPI Settings".
2. Open the tab "Recipient fields".
3. Scroll to the bottom and click "Add another field".
4. Fill in the fields which appear:
   • Name should be filled with a consise label for the field. Preferably just one, or at most, a very short sentence.
   • Field ID should just be filled with the same name as above [^Field ID]
   • Description is a help text where you can type in instructions on what to enter (or not to enter) into the field, when filling out a "Create recipient" form.
   • Type is perhaps the most interesting field. Here you can pick what data the field may accept. You can also add "multiple choice"-types, making it possible to force the user to select from a predefined list of options.

5. Optional step: If you want to re-arrange the fields, drag the tall button left of the labels. This will rearrange the field - drag it up, to make it come earlier and down to make it come later in the form.

Note: You can delete any field that you have added. It is however not possible to delete the built-in fields (name, country code and phone), though you may rename them.

You should now go ahead and try to create a new recipient or edit an existing one. The field(s) you have added, should now be presented on the create/edit page of the recipient.

[^Field ID]: Field ID is technically the "meta key" under which the field value for each recipient is stored. Changing this value on a field does not "move" the data from the old Field ID/meta key to the new one, so data may be lost. In other words, it's usually best to pick a Field ID and never change it.

If you have been through all steps above, ie. you have set up the plugin, added at least one recipient, added the recipient to a group and perhaps even added one or more custom fields, then you are now ready to send your first SMS to your recipients.

1. Go to "SMS'es" » "Create SMS".
2. To send to one or more of your groups, check off "Use recipient groups". Then you can select groups to send to, from the list which just appeared. The group moves from the left to the right list, to clearly indicate that it has now been seleted.
3. The number right next to the group names, shows how many recipients are in the group. [^Recipient count in groups]

4. To undo adding a group, just click the checkbox again.
5. Now write your message.
   • You can optionally also change the type of SMS, but in most cases the default is fine. In regards to "Sender", then this defaults to the Sender you specified in the "GatewayAPI Settings", if you leave it empty.
   • You can use "tags" to dynamically insert values from your recipients. This way you can personalize your SMS'es to reflect each recipient.

6. When you are finished, use have the following options in the "Send"-box to the right:
   • Just clicking "Send" schedules your SMS for immediate delivery.
   • "Save draft" lets you save the SMS and continue working on it later.
   • If you want to send the SMS in the future, click "Edit" next to "Send immediately". The "Send"-button changes to "Schedule". [^WordPress Cron vs Schedule Time]

[^Recipient count in groups]: Recipient count in groups shows how many recipients are in a given group, but as the same recipient may be in multiple groups, you cannot necessarily just add the numbers together to find out how many recipients you are about to send to. [^WordPress Cron vs Schedule Time]: Scheduling an SMS makes WordPress send the SMS as soon as WordPress "wakes up" after date/time defined. Ie. if there are no visitors on your website at the specified send time, then the SMS will not be sent at the planned time, but it will be sent as soon as the next visitor hits the site. Fo high traffic websites, this should not be an issue, but if you, say, just have a single visitor an hour, then the SMS may be delayed by that one hour. This is a limitation in the way WordPress handles background tasks such as scheduled publishing (cron jobs).

The plugin supports a very simply copy-paste based approach for importing recipients from Excel (or any other spreadsheet-application for that matter).

If you need to import a list of recipients from a spreadsheet, then you need to prepare the spreadsheet, by making sure the following columns exist (at least):

• Phone number without country code prefix!
• Country code field [^List of country calling codes]. If all recipients are from the same country, just add a column where everybody has the same value.

Each column must start with a row with the column names. The names are not important, but it is important that you don't start right off with recipient data.

We also recommend that you add a column for name.

In the following example spreadsheet, columns has been added for the built-in values (name, country code and phone number) as well as a custom field "birth year".

With the data preparation out of the way, you can now import the data into the plugin, having it converted into recipients. Existing recipients will be updated. No recipients will be deleted. Only columns added will be updated.

To import the spreadsheet:

1. Open your spreadsheet.
2. Select all rows and columns. Copy the content.
3. Go back to the plugin.
4. Open "SMS'es" » "Import recipients".
5. Focus in the big textarea and simply paste the content.
   • Simply ignore that the columns are not aligned. The plugin will correct this momentarily.

6. Click "Analyze data".
7. On the next screen, you are able to match up the columns from the spreadsheet, with the fields available on each recipient.

8. You should also select at least one group which the recipients should be added to.
9. Click "Import" and wait. This may take a while, depending on the amount of recipients.

All of the recipients from your spreadsheet should now exist under "SMS'es" » "Recipients".

[^List of country calling codes]: You can find a complete list of country calling codes at [countrycode.org](https://countrycode.org).

In order to receive SMS'es you need to either own an entire phone number in one or more countries, or get a keyword on one of our phone numbers. In Denmark for instance, we own the phone number/short code 1204, so you can have SMS'es sent to number 1204 + some keyword of your choice, sent to you.

A keyword is a single word and it is the first word the user must type in the SMS.

Depending on your needs, you may need a full phone number in your local country. In this case you may own the entire number and all texts sent to it, will be forwarded to you.

To get a keyword and/or a phone number for SMS receiving, you must:

• Go to GatewayAPI.com and log in.
• Contact Support.
  • Specify which country/countries you need to receive SMS'es in.
  • We will suggest various options.
  • Once we have come to an agreement, the keyword will be added to your account.

If you have completed the above steps, you are now ready to setup the number/keyword. Do the following:

1. Go to your WordPress installation.
2. Open "Settings" » "GatewayAPI Settings".
3. Go to the tab "SMS Inbox".
4. Toggle the "Yes please, I would like to receive SMS messages.".
5. Click "Save Changes".
6. Select and copy the URL in the text field near the bottom of the page.

7. Go to GatewayAPI.com and log in to your account (open the dashboard).
8. Visit gatewayapi.com and click "Settings" » "Web Hooks".
9. Click "ADD NEW" in the "REST"-section.

10. Enter a Unique label. You may write anything to help you identify the connection.
11. Paste the URL from step 6 into the "Web hook URL"-field.

12. Go to the "Keywords"-tab and select the keywords you want WordPress to handle.
13. Click "Save" (on "Endpoint settings"-tab).

Some users have asked for the possibility to modify the columns on the list of recipients. We have decided that there's no reason to build this feature, as excellent third-party plugins exists for this.

To add/remove columns of the Recipients-list, or any othe of the lists for that matter, we recommend installing the plugin "Admin Columns".

For more instructions on how to install and use, you should check out the plugins page on WordPress: [Admin Columns on WordPress.org](https://da.wordpress.org/plugins/codepress-admin-columns/)

To allow your visitors to sign up, edit their profile and unsubscribe, we provide WordPress shortcodes which generates forms for frontend use. They automatically expose the custom fields etc. and supports a SMS-confirmation flow, ensuring that the visitors actually own the number they are entering.

Finally we also include a "Send SMS"-form, which enables you to send SMS'es from the frontend. Please be warned though: If the page on which you include this shortcode is not properly secured, you may risk any visitor being able to send SMS'es on your behalf!

We are also including a shortcode generator wizard, which makes it very easy to create the required shortcode.

To generate a shortcode, do the following:

1. Go to "Settings" » "GatewayAPI Settings".
2. Open the tab "Build Shortcode".
3. Follow the on-screen instructions.
4. Select and copy the shortcode from the bottom-most textarea.

5. Open any page or post in the WordPress backend.
6. Paste the shortcode where you want the form on the page.

The forms are somewhat unstyled. They will usually fit into most themes quite fine. We decided on not applying any styles to the form, but instead leave your site with high quality HTML5-markup, leaving it up to you how to style the form using CSS. Most webmasters prefer that we do not enforce any styles from our end, giving the webmaster the highest degree of freedom.

Please inspect the output of your website, to find out what CSS class names we use etc. and create a stylesheet that matches your website design.

Some of our users have expressed a desire to base their recipients off the WordPress user database. In order to meet this need, we have created an automatic synchronization mechanism, which automatically copies any new and updated users from the WordPress user database and into the GatewayAPI recipients.

All relevant metadata on the users will be copied as well. You just need to add recipient fields with field ids matching the meta keys on the user.

To enable this feature:

1. Go to "Settings" » "GatewayAPI Settings".
2. Open the tab "User synchronization".
3. Follow the on-screen instructions.

As the users are only synchronized on change/creation, you will need to do a one-time synchronization in case you already have users created. In case you find the recipients database out of sync with your users, you are also most welcome to re-run the one-time synchronization.

Simply check the "Synchronize all existing users on submit" checkbox and hit "Save Changes".

If you install the Advanced Custom Fields-plugin, then you can easily create/work with the required extra meta fields on the user. For instance, you could create the following fields on the "User Form"-pages:

Then, when you edit a user, it will look like this:

With that in place, the users with phone numbers, country code and optinally any extra meta fields, can be easily synced by entering the "field names" (not the "field label"!) into the User Synchronization-tab:

Many users prefer to use other third party plugins for creating website forms. Though we have put very hard work into our own shortcodes, we felt that this would never be an option for some users, who prefered continuing with their existing form tools.

We decided to integrate fully with Contact Form 7, as it is a free and mature plugin for creating forms on WordPress-sites. Though the name suggest this to be perhaps just a "contact form"-plugin, the plugin sports a very capable and extensible engine - just like WordPress was initially intended for just blogging, this plugin has come a long way from just being a simple contact form-plugin.

Contact Form 7 give you a lot of freedom which is mostly good, but it also demands a little more on your part in order to get the forms working properly.

If you haven't already installed [Contact Form 7](https://wordpress.org/plugins/contact-form-7/) into your WordPress, then please go ahead and do that now.

When you go and edit or create a new form, then we have added a few new actions to the editor and a new tab.

In order to create any form dependent on the GatewayAPI-features, you must add a hidden field specifying the intended action of the form. This hidden field is easily generated by clicking the "action*"-button in the toolbar.

To create a signup form, add at least the following fields:

• phone
• country code
• groups
• action (set to signup)

The steps are the same as for creating a "Signup form", but we have a few extra requirements:

• All of your fields, including labels, should each be wrapped in a <div> tag.
• The action must be set to "update".

The reason is, that we initially hide all fields except phone number and country code, in order to allow the user to "log in" by means of SMS-verification. As soon as the phone number is verified, all profile information is then copied into the fields which are then shown, and the user can update his profile.

If there are groups that you have not added to the form, their values will remain unchanged for the user. This way you can have "internal" groups that are never exposed to the public.

To create a signup form, add at least the following fields:

• phone
• country code
• action (set to unsubscribe)

We include support for building a "Send SMS"-form, which enables you to send SMS'es from the frontend. Please be warned though: If the page on which you include this shortcode is not properly secured, you may risk any visitor being able to send SMS'es on your behalf!

To create a form for sending SMS'es, you must at least add the following fields:

• groups
• smstext
• action (set to sms)

Note: It is not possible to send SMS'es from the frontend, to manually added recipients - all recipients must be in one or more of the selected groups.

You can create any Contact Form 7 which sends an SMS auto-reply to the user. Simply add a country code field and a phone number field to the form and enable the "SMS Reply" feature in the "SMS Reply"-tab.

Contact Form 7 by default simply shows an alert and clears all fields when a submission was succesful. In case you would like to clear the screen, the best approach is to redirect the user to another page. You should therefore set up another page and copy the full URL to that page.

Once done, go to the last tab of your form, the tab named "Additional Settings". Here you should enter the following setting:

on_sent_ok: "location='YOUR URL HERE';"

Where YOUR URL HERE should be replaced with the URL to the page that you just created. Be aware that you have exactly as many quotes as shown above, otherwise you may break your site.

The default behaviour of Contact Form 7 is to send you a mail with the entered data (Contact Form 7 is still intended mostly for regular contact forms). This might become slightly annoying, when the forms are used for updating profiles etc.

You can easily disable these notifications on a form, by going to the "Additional Settings" tab on a form, and adding the following line in the textarea:

demo_mode: on

Yes, it says "demo_mode", but everything is working exactly as it should - the only difference is, that it skips delivering mails to you.

Do you have any feedback to this manual or the plugin in general? Any great ideas for improvement, missing features, spotted a really annoying typo etc.? Then please don't hesitate to get in touch with us!

Send us a mail at [email protected] or use the chat widget on GatewayAPI.com. We're on at most hours of the day and on most days.