Getting Started
Quick start
Installation process is pretty easy, here is what you are to do:
- Download and unzip your copy of Callme
- Buy a license (optional)
- Change config file to get fields you need in your form.
- Set up e-mail and SMS notifications
- Upload files via FTP
- Update your website template
Have fun, you're good to go! 🎉
Built-in Form
You can handle any of the forms, which are built in your page. To make it work you need to create a custom form and assign it a new attribute data-callme-form
, submit button should send this form:
<button type="submit" data-callme-action="submitForm" class="">Send form</button>
Add proper attribute for required fields: data-required="true"
.
Make sure all fields have name
attributes. It will be used for naming fields in notification.
The result of processing can be displayed in any element inside the form. These may be errors, sending process or success message.
You may want to create an element inside the form with an an attribute data-callme-result
.
Installation
After you set up all your files and upload them to your website, add this single line to your template:
<script src="/callme/js/callme.min.js" charset="utf-8"></script>
If you use other folder than /callme
, update the url:
<script src="/__folder__/js/callme.min.js" charset="utf-8"></script>
It's important to add it to the file that is being included to all the pages. E.g. footer or header.
jQuery library
Callme has a jQuery dependancy so you should have your jQuery installed before Callme:
<script src="/callme/js/jquery.js"></script>
In most cases you already have this library. If not, go grab your copy of a libraryhere.
Custom invokers
You can invoke any of the forms by clicking on any object on the page. It can be hyperlink, image, button, random inline or block element etc.
To make this happen just add attribute data-callme-config='__config__'
class to the object. If you omit the value for the attribute, "main" config will be used.
Replace __config__
with the exact name of your config file (excluding '.js').
<a href="#" data-callme-config>Click me!</a>
<a href="#" data-callme-config='short-default'>Click me!</a>
In older versions you could use a class instead of data-attribute:class='callme_viewform'
. You still can use class but data-attr is preferrable.
Events
Every time something happens with any of your callme forms, there are custom events triggered in your jQuery $('window')
object.
You can easily bind any actions. I.e. Google anayltics report.
EcmaScript6 syntax:$(window).on('callme.close.finish', () => console.info('Callme form closed'))
EcmaScript5/JS syntax:$(window).on('callme.close.finish', function() {
console.info('Callme form closed'));
}
List of events
Event | Description |
---|---|
callme.load.finish | This event is triggered when callme settings are loaded |
callme.close.start | This event is triggered when form starts closing |
callme.close.finish | This event is triggered when form finishes closing |
callme.show.start | This event is triggered when form starts to appear |
callme.show.finish | This event is triggered when form is finished appearing |
callme.request.finish | This event is triggered when sending request finishes |
callme.request.fail | This event is triggered when sending request fails |
callme.captcha.error | This event is triggered when captcha has errors while submitting form |
callme.submit.start | This event is triggered when form submit button is clicked |
callme.submit.fail | This event is triggered when form submitting fails |
callme.submit.finish | This event is triggered when form is successfully submitted |
callme.formCreate.finish | This event is triggered when a new form is created |
Link markers
If you have multiple forms on your pages you can easily track which of the links was used to make a request. All you need is to add adata-cme
attribute to the object that calls the form:
<button data-callme-config data-cme="link attribute #1">Click me!</button>
Settings example
{
"button": {
"show": true,
"text": "Short form"
},
"fields": [
{
"type": "text",
"name": "Your Name",
"placeholder": "Type your name",
"required": true,
"sms": true
},
{
"type": "tel",
"mask": "(999) 999-9999",
"name": "Phone Number",
"required": true,
"sms": true
}
],
"form": {
"template": "fb",
"title": "Request a callback",
"button": "Request",
"class": "form-center",
"welcome": "Fill in the form and we'll call you back as soon as possible"
},
"alerts": {
"yes": "Yes",
"no": "No",
"process": "Sending request...",
"success": "Your request was successfully sent",
"fails": {
"required": "Please fill in all required fields",
"sent": "Previous message was sent less than a minute ago"
}
},
"captcha": {
"show": true,
"title": "Captcha",
"error": "Captcha is wrong"
},
"license": {
"key": "143022181824244220151218223020182821163618181630221820143022",
"show": false
},
"mail": {
"referrer": "Page referrer",
"url": "URL",
"linkAttribute": "Link attribute",
"smtp": true
},
"animationSpeed": 150,
"sms": {
"send": false,
"captions": true,
"cut": true
}
}
Explaining settings
Field | Purpose | Type |
---|---|---|
button | Floating button settings | [object] |
fields | List of fields to be shown in current popup form. | [array] |
form | Form settings: style, text captions, positioning | [object] |
alerts | Text captions to be shown in alerts (success, error or sending process) | [object] |
captcha | Captcha settings: visible or not and an error message | [object] |
license | After buying a license you can add it to your config.js file to get more functionality and hide the copyright link (optional). Note that license key is set to a domain and needed to be added to every of config file. In most cases you'll have only one config file. | [object] |
mail | Settings for email notifications. Here you can set up texts that will be sent in email. | [object] |
animationSpeed | Animation speed for the form, set in microseconds. E.g. 1 second is 1000 ms. | [number] |
button
Floating button settings.
Field | Purpose | Type |
---|---|---|
show | Whether to show or hide the floating button on the right side (true/false) | [boolean] |
text | Button caption. E.g. "Request a callback" or "I need help". | [string] |
fields
Array of objects for the fields to be displayed in the form. Callme works with field types listed below.
Here's an example of field
{
"type": "text",
"name": "Your Name",
"placeholder": "Type your name",
"required": true,
"sms": true
}
Text field
<input type="text" />
Classic text field. Arguments:
- type
- text
- name
- string
- placeholder
- string
- required
- boolean
- sms
- boolean
<input type="email" />
Email field, will be validated if filled. Arguments:
- type
- name
- string
- placeholder
- string
- required
- boolean
- sms
- boolean
Phone
<input type="tel" />
Phone number with a mask. Arguments:
- type
- tel
- name
- string
- mask
- text mask for the field, e.g.
"(999) 999-9999"
- required
- boolean
- sms
- boolean
Textarea
<textarea type="email"</><textarea>
Textarea, arguments:
- type
- textarea
- name
- string
- placeholder
- string
- required
- boolean
- sms
- boolean
Dropdown
<select>...</select>
Dropdown list. "options" should have an array of available options for the select.
- type
- select
- name
- string
- options
- array
- sms
- boolean
Checkbox
<input type="checkbox /">
Checkbox. If you set "required" to be truthy, Callme form won't be submitted until the checkbox is checked.
- type
- checkbox
- name
- string
- caption
- string (a text to replace the checkbox caption, allows HTML)
- required
- boolean
- sms
- boolean
form
Form settings.
Field | Purpose | Type |
---|---|---|
template | Choose a template to be used for the form. E.g. "fb" or "default" | [string] |
title | Form title, e.g. "Request a callback" | [string] |
button | Button caption title, e.g. "Call Me" | [string] |
align | You can either show the form in the middle of the screen sticked to the left or right corner. To change form position use values:left orright | [string] |
welcome | Welcome text, default is "Fill in the form and we'll call you back as soon as possible" | [string] |
Alerts
Text captions that are being used for form captions
Field | Purpose | Type |
---|---|---|
yes | Yes (si, так, ja etc.) | [string] |
no | No | [string] |
process | Caption showing while request is being sent. E.g. "Sending request..." | [string] |
success | Successfully sent alert. E.g. "Your request was successfully sent" | [string] |
fails | Possible reasons for request to be cancelled | [object] |
Alerts → fails
Possible reasons for request to be cancelled. Please note that if you set no fields to be required, all of them will be required.
Field | Purpose | Type |
---|---|---|
required | If not all required fields are filled. E.g. "Please fill in all required fields" | [string] |
sent | The form can't be submitted if the previous request from this visitor was sent less than a minute ago. E.g. "Previous message was sent less than a minute ago". | [string] |
Captcha
If you use a licensed script, you can use captcha to upgrade the security of the form. If you don't have the license, these settings will be ignored.
Field | Purpose | Type |
---|---|---|
show | Show captcha? true/false | [boolean] |
title | Text to be shown before captcha. E.g. "captcha" or "Enter code" | [string] |
error | Captcha error. Shows if captcha was filled wrong. E.g. "Captcha is wrong" | [string] |
License
Here you can add your license key. The key is unique for a domain (or subdomain) and if anybody else gets your license it won't work on other website. If you have multiple forms you should add license key to all of configs.
Field | Purpose | Type |
---|---|---|
key | The key you've got from developers after buying a license. | [string] |
show | Should form copyright be visible? If you want to support the script, you can leave copyright in it (and we'll be thankful for you doing that). | [boolean] |
Mail settings. Captions to be sent in email notifications.
Field | Purpose | Type |
---|---|---|
referrer | Caption for the referrer, the page where visitor came from. E.g. "Page referrer". | [string] |
url | Caption for the page url where the request was sent from. E.g. "URL". | [string] |
linkAttribute | If you use link captions to track the link used for request, here's the place to name this field. E.g. "Link attribute". | [string] |
smtp | Use smtp for email notifications? If "false" php sendmail() method will be used. | [boolean] |
Animation
Field | Purpose | Type |
---|---|---|
animationSpeed | The speed for animations duration for the form. E.g. 150. | [integer] |
Mail settings
Mail settings can be changed inphp/go.php
. There are two ways to make e-mail notifications work: SMTP and native PHPmail()
function.
PHP sends letters much faster but SMTP is a more reliable way, which can almost guarantee that letter won't appear in spam.
That's it. If you your notification style to be changed, you can dig into$message
variable.
Variable | Purpose | Type |
---|---|---|
$to | This is the main (and mostly the only) variable to be changed to make Callme work properly. You can set your email or couple of emails here (separated by comma) to get users' notifications. Here's an example: $to = 'yourmail@gmail.com'; | [string] |
$from_user | If this variable is code $from_user = true; | [boolean] |
Choosing receiver for notification
You can allow user to choose the receiver of notification. For instance, it could be a different department depending on the option chosen.
This setting is to be done in two steps:
in
php/go.php
you need to change the$to
variable. Put here an array of emails of the receivers.Example
$to = array('department_1@mail.com', 'department_2@mail.com', 'department_3@mail.com');
After this your need to add another field into your config file:
receiver
, where inoptions
you may want to add names for each of the receivers.Example
{ "type": "receiver", "name": "Department", "sms": false, "options": [ "Sales department", "Problems", "Advertisement" ] }
The user won't see email addresses.
SMTP settings
You set notifications to be sent via SMTP, the settings can be found inphp/smtp.php
Please note: this file will be ignored until you setmail → smtp
to betrue
in your config file.
Variable | Purpose | Type |
---|---|---|
$config['smtp_username'] | SMTP username | [string] |
$config['smtp_port'] | SMTP port | [integer] |
$config['smtp_host'] | SMTP server. See examples below | [string] |
$config['smtp_password'] | Your SMTP password | [string] |
$config['smtp_charset'] | Message encoding, in most cases it should be'utf-8' | [string] |
$config['smtp_from'] | Sender name, it'sCallme by default. | [string] |
Gmail settings
If you use Gmail (hopefully you do), you'll need to turn on 2-step verification and generate an application password. It's easy to do, all you need is to follow these instructions:
The password you generate there should be used for Callme.
SMTP Server
Server address. In most cases you'll need one of these:
- Gmail
- smtp.gmail.com
- Yahoo
- smtp.mail.yahoo.com
- Yandex
- ssl://smtp.yandex.ru
SMTP port
Ports are used most for services:
- Gmail
- 25, 465 and 587
- Yahoo
- 465 and 587
- Yandex
- 465
SMTP docs
You can find detailed docs here:
SMS settings
SMS settings can be found inphp/sms.php
You can choose which fields should be sent in sms and which to be omitted. Take a look at fields' settings for your config files to see examples.
To start with SMS you need to create an account at one of the SMS-services. Currently Callme supports these services:
Yes, some of sms-services have referral links and in theory I can get 5-10% of your spendings
Do you work at SMS-service with good prices and ability to send messages to major countires? Contact me if you want your service to be added to the list.
SMS settings are stored in thesms
object with these settings:
Variable | Purpose | Type |
---|---|---|
send | Whether to send sms or not | [boolean] |
captions | Do you need captions for fields? E.g. you can receiveyou name: christian, phone: +1-123-123-1122 or christian, +1-123-123-1122 | [boolean] |
cut | If set to true, sms messages will be truncated up to 160 symbols | [boolean] |