Callme documentation

Quick start, email, SMTP and sms settings

Getting Started

Installation process is pretty easy, here is what you are to do:

  1. Download and unzip your copy of Callme
  2. Buy a license (optional)
  3. Change config file to get fields you need in your form.
  4. Set up e-mail and SMS notifications
  5. Upload files via FTP
  6. Update your website template

Have fun, you're good to go! 🎉

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.

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.

💡 You can create as many config files as you may need

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.

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>
🕹 Go try it: click me or better click me

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.

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'));
}
EventDescription
callme.load.finishThis event is triggered when callme settings are loaded
callme.close.startThis event is triggered when form starts closing
callme.close.finishThis event is triggered when form finishes closing
callme.show.startThis event is triggered when form starts to appear
callme.show.finishThis event is triggered when form is finished appearing
callme.request.finishThis event is triggered when sending request finishes
callme.request.failThis event is triggered when sending request fails
callme.captcha.errorThis event is triggered when captcha has errors while submitting form
callme.submit.startThis event is triggered when form submit button is clicked
callme.submit.failThis event is triggered when form submitting fails
callme.submit.finishThis event is triggered when form is successfully submitted
callme.formCreate.finishThis event is triggered when a new form is created

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>
{
	"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
		}
}
FieldPurposeType
buttonFloating button settings[object]
fieldsList of fields to be shown in current popup form.[array]
formForm settings: style, text captions, positioning[object]
alertsText captions to be shown in alerts (success, error or sending process)[object]
captchaCaptcha settings: visible or not and an error message[object]
licenseAfter 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]
mailSettings for email notifications. Here you can set up texts that will be sent in email.[object]
animationSpeedAnimation speed for the form, set in microseconds. E.g. 1 second is 1000 ms.[number]

Floating button settings.

FieldPurposeType
showWhether to show or hide the floating button on the right side (true/false)[boolean]
textButton caption. E.g. "Request a callback" or "I need help".[string]

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
}

<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
email
name
string
placeholder
string
required
boolean
sms
boolean

<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 type="email"</><textarea>

Textarea, arguments:

type
textarea
name
string
placeholder
string
required
boolean
sms
boolean

<select>...</select>

Dropdown list. "options" should have an array of available options for the select.

type
select
name
string
options
array
sms
boolean

<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 settings.

FieldPurposeType
templateChoose a template to be used for the form. E.g. "fb" or "default"[string]
titleForm title, e.g. "Request a callback"[string]
buttonButton caption title, e.g. "Call Me"[string]
alignYou 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]
welcomeWelcome text, default is "Fill in the form and we'll call you back as soon as possible"[string]

Text captions that are being used for form captions

FieldPurposeType
yesYes (si, так, ja etc.)[string]
noNo[string]
processCaption showing while request is being sent. E.g. "Sending request..."[string]
successSuccessfully sent alert. E.g. "Your request was successfully sent"[string]
failsPossible reasons for request to be cancelled[object]

Possible reasons for request to be cancelled. Please note that if you set no fields to be required, all of them will be required.

FieldPurposeType
requiredIf not all required fields are filled. E.g. "Please fill in all required fields"[string]
sentThe 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]

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.

FieldPurposeType
showShow captcha? true/false[boolean]
titleText to be shown before captcha. E.g. "captcha" or "Enter code"[string]
errorCaptcha error. Shows if captcha was filled wrong. E.g. "Captcha is wrong"[string]

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.

FieldPurposeType
keyThe key you've got from developers after buying a license.[string]
showShould 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.

FieldPurposeType
referrerCaption for the referrer, the page where visitor came from. E.g. "Page referrer".[string]
urlCaption for the page url where the request was sent from. E.g. "URL".[string]
linkAttributeIf you use link captions to track the link used for request, here's the place to name this field. E.g. "Link attribute".[string]
smtpUse smtp for email notifications? If "false" php sendmail() method will be used.[boolean]

Animation

FieldPurposeType
animationSpeedThe speed for animations duration for the form. E.g. 150.[integer]

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.

VariablePurposeType
$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 true, user email from email field in the form will be set as sender address. If there are multiple email fields, the latest will be used. Keep in mind: changing of sender may not be supported by some kind of mail services.

code $from_user = true;
[boolean]

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:

  1. 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');

  2. After this your need to add another field into your config file: receiver, where in options 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.

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.

VariablePurposeType
$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]

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:

  1. Two-step Verification
  2. Create an application password

The password you generate there should be used for Callme.

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

Ports are used most for services:

Gmail
25, 465 and 587
Yahoo
465 and 587
Yandex
465

You can find detailed docs here:

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 thesmsobject with these settings:

VariablePurposeType
sendWhether to send sms or not[boolean]
captionsDo you need captions for fields? E.g. you can receive
you name: christian, phone: +1-123-123-1122
or
christian, +1-123-123-1122
[boolean]
cutIf set to true, sms messages will be truncated up to 160 symbols[boolean]