Marcelo Gornstein edited this page Mar 2, 2017 · 272 revisions

General

Concepts

Pricing

Billing

Number Verification

Number Inspect

CNAM Database Lookups

PortaSMS

SMS

SMS Services and Short Codes

MMS

Bulk SMS

Telephony

Alerts and Notifications

REST API


General

How can I contact you?

If you are in trouble or need support, email our Support team at support@portatext.com, this will automatically create a ticket in our Support Center. We'll get back to you as soon as possible!

You can contact us:

How does PortaText work?

PortaText will let you reach your customers in the entire world directly to their mobiles, by sending and receiving SMS, either from your panel or from your own application by using our REST API or one of our Available SDKs.

You can send individual messages or do bulk sending with our SMS Campaigns. We also support templates so you can customize the text based on variables.

To send messages you have to acquire one or more DIDs (telephone numbers) from us, or one or more "SMS Services" (i.e: short codes) and then "pay as you go" when using the service. See also What is the difference between a long code and short code?.

Each SMS you send has a cost in "credits" (depending on the destination), and you can buy credits at any time with your credit card.

Please contact us, our team will be happy to clear any questions you might have.

Can I integrate my current application with PortaText?

Absolutely! We offer a clean REST API that allows you to completely manage your account, and we've also have some Available SDKs for different programming languages that you can easily use from your applications.

If you don't find your favorite programming language, please contact us and we'll be glad to help you integrate with us!

How can I open my account?

Go to our website https://www.portatext.com/signup and create your free account in no time. You will then be able to obtain an API key and your username/password.

Do you support "short codes" and/or "keywords"?

We do support shared short codes, based on keywords. We call this an SMS Service. For more information see SMS Services and Short Codes

What kind of technologies do you use at PortaText?

We try to pick the right tool for the job, so we do use a wide set of technologies at PortaText. You can see a detailed list of versions for each one of the following in your panel or via the version API:

I don't see my question. What should I do?

Please contact us and let us know your question. We'll be happy to answer and add it here so it can help others as well :)

I'd like to use PortaText for my business, but I need X feature. Can you guys do it?

Sure! We always try to do our best to support our clients and improve our services, and who's better to suggest new features that our own clients? Please contact us and let us know what you need and we'll work something out!

Where can I read about Best Practices for SMS Marketing Campaigns and Notifications?

We make sure to guide our users throughout the whole process of setting up a campaign and using our services so they can take full advantage of our features. You can read more at out blog at https://blog.portatext.com/:

Also, make sure that you read and are familiar with the TCPA and E-SIGN laws if you are going to contact people in the US.


What's the CSV format that I should use to create campaigns, or import contacts, contact lists, and variables?

To import contacts, contact lists, and their variables, you should use a standard CSV with line endings in either UNIX or DOS format, and the first line MUST be the headers (i.e: variable names). Here's an example:

number,first_name,last_name
12223334444,John,Doe
13334445555,Albert,Beckenbauer

In this case we're importing 2 contacts with 2 variables each one, named first_name and last_name.

NOTES:

  • When importing your contacts, your old list will be deleted and replaced by this new one.
  • The column "number" MUST be the first column (field) in the CSV file.

Can I connect with SMPP to your platform?

Not at the moment. Although we do use SMPP to connect to some carriers, we don't offer an SMPP interface to our platform for our clients, mainly because we find that an HTTP interface offers some advantages:

  • Better scaling: you can issue as many HTTP requests as you need and we can scale our systems in order to support more requests from you and other clients (and you can also use HTTP 1.1 so you can issue many requests by reusing the same connection).
  • Easier to extend: With an HTTP REST API like we offer, we are able to extend our services by adding new features in a clean and idiomatic way.
  • Easier to use: We offer open source SDKs for many different programming languages that make it really easy to use our services, but also almost any programming language has now a way to make HTTP requests, so anyone can use our services in their language of choice.
  • Less implementation details to know about: By using HTTP we free you from taking some decisions like best encoding for your text (GSM, UCS2, 7bits, 8bits, etc), message concatenation for MOs and MTs, etc.

Concepts

What is a DID or long code?

DID stands for Direct Inward Dial, and is basically speaking your unique telephone (or virtual) number in a country. When referring to the SMS world, this is also known as a "Long Code". See also What is the difference between a long code and short code?

Qué es "LVN" o "Long Virtual Number"?

See What is a DID or long code?.

What is a short code?

"Short codes" consist in 5 or 6 digits and these are unique and accessible only inside a specific country, and not in the rest of the world). See also What is the difference between a long code and short code?

What is an SMS Service?

See What is an SMS Service, and how it is related to a Short Code?.

What is P2P and A2P and how they relate to SMS?

P2P is short for Person-To-Person while A2P means Application-To-Person. We use these terms when discussing how SMS are being used in a specific context.

P2P means that messages are exchanged between humans, and A2P means that messages flow between humans and applications (software).

Applications can use SMS to offer different services for clients and users. Adding SMS as an extra channel to communicate with your customers is a great way to enhance your customer experience. You can read more about A2P in our blog post SMS A2P is on! Are you?.

What is the CNAM Database?

CNAM means Caller ID Name. Carriers sometimes make the CNAM database available for different countries so you can get the associated name of a telephone number. We provide this service that can greatly enhance your leads. See the section CNAM Database Lookups.

What is CTA or Call-To-Action?

To quote the Wikipedia Entry:

In marketing, a call to action (CTA) is an instruction to the audience to provoke an immediate response, usually using an imperative verb such as "call now", "find out more" or "visit a store today".[1]

A CTA can be a simple non-demanding request like "choose a colour" or "watch this video", or a much more demanding request. An obvious CTA would be requesting the audience to purchase a product or provide personal details and contact information.

You can read more in our blog at Creating Great Call-To-Action Text For Your SMS Campaigns.

What is "Number Verification"?

Verifying a mobile phone number is a great security enhancement to your business. It allows you to be certain that a specific phone number belongs to a specific client or user by sending a code via SMS and asking for that code later on in a web page or in a telephone call. See Do you provide a way to authenticate mobile phone numbers?.

What is "Number Inspect"?

This feature allows you to get a lot of information of a phone number, including if it's a landline or mobile number. This is useful for example to pre-filter the list of your contacts so you don't spend credits sending SMS to landline phone numbers in your campaigns.

It's also useful to know the MNO and country of a phone number.

For more information see:

What is "SMPP" or "Short Message Peer-to-Peer"?

SMPP is the protocol used to exchange SMS messages between Short Message Service Centers (SMSC) and/or External Short Messaging Entities (ESME).

What is "PDU" or "Protocol Data Unit"?

When talking about SMS, a PDU often means a "Protocol Data Unit" of the SMPP protocol. A PDU is the minimum unit of data exchanged between peer entities (in the same layer) of a network.

What is "SMSC" or "Short Message Service Center"?

In the SMPP protocol, a Short Message Service Center (or SMSC) is a network element in the mobile telephone network. It stores, forwards, converts and delivers SMS messages.

What is "ESME" or "External Short Messaging Entity"?

In the SMPP protocol, an External Short Messaging Entity (or ESME) is an external application that connects to a Short Message Service Center (SMSC) to engage in the sending and/or receiving of SMS messages.

What is "MT" or "Mobile Terminated"?

The term "Mobile Terminated" is used to describe text messages that are sent to a mobile/cellphone device, the messages terminates on a mobile device. See also What is "MO" or "Mobile Originated"?. These are "outbound" messages, the ones you send through PortaText.

What is "MO" or "Mobile Originated"?

The term "Mobile Originated" is used to describe text messages that are sent from a mobile/cellphone device, the messages originate on a mobile device. See also What is "MT" or "Mobile Terminated"?. These are "inbound" messages, the ones you receive with PortaText.

What is "DLR" or "Delivery Receipt"?

A delivery receipt, sometimes or DLR, is a notification sent from the MNO to the sender. It contains the delivery status for that message (i.e: if it was delivered successfully or not). Note that a success status means that the message was accepted by the mobile network, and not that it was actually delivered to the handset. You can read more about how to receive DLRs in your application in our Notifications wiki page.

What is "GSM" or "Global System for Mobile Communications"?

GSM is a standard developed by the European Telecommunications Standards Institute (ETSI), describing all the protocols that compose the 2G cellular networks used in mobile communications. 3G and 4G (also known as LTE) are not part of the ETSI GSM standard.

Over time GSM was expanded to include data communications, first by circuit-switched transport, then by packet data transport via GPRS (General Packet Radio Services) and EDGE (Enhanced Data rates for GSM Evolution or EGPRS).

What is "GSM 03.38" or the "GSM charset"?

The GSM 03.38 Recommendation is a character set used in the Short Message Service of GSM based cell phones.

Messages sent via this encoding can be encoded in the default GSM 7-bit alphabet, the 8-bit data alphabet, and the 16-bit UCS-2 alphabet.

In a standard GSM text message, all characters are encoded using 7-bit code units, packed together to fill all bits of octets. So, for example, the 140-octet envelope of an SMS, with no other language indicator but only the standard class prefix, can transport up to (140*8)/7=160, that is 160 GSM 7-bit characters.

A single SMS GSM message using UCS-2 can have at most 70 characters (140 octets). This encoding allows use of a greater range of characters and languages. UCS-2 can represent the most commonly used Latin and eastern characters at the cost of a greater space expense.

See also "How are my messages billed?".

You can also read more in our blog post "Unicode in your SMS: Emojis and Non-English Characters".

Here you can find the complete GSM 03.38 character set. You can also get the full character list by using your panel, or the GSM Charset API Endpoint from one of our available SDKs.

What is "MNO" or "Mobile Network Operator"?

A Mobile Network Operator (MNO) is an organization that owns and/or controls all the network equipment and licenses needed to operate in a radio spectrum, and provides wireless telecommunication services to end users, including billing.

An MNO may also sell access to network services at wholesale rates to Mobile Virtual Network Operators

See also: Where can I get a list of all the mobile network operators?.

What is "MVNO" or "Mobile Virtual Network Operator"?

A Mobile Virtual Network Operator (MVNO) is an organization that provides wireless telecommunication services to end users, including billing. It does not have access to its own network so it offers its services via an agreement with an MNO so they can use their infrastructure.

See also: Where can I get a list of all the mobile network operators?.

What is "ITU" or "International Telecommunication Union"? What is the "ITU-T"?

The ITU is the International Telecommunication Union. It's a Specialized Agency of the United Nations responsible for all things concerning information and communication technologies. Among many other things it is responsible for creating technical standards to be used in devices and protocols concerning data, voice, TV broadcasting, next-generation networks and many other fields.

ITU-T is the Telecommunication Standardization Sector, and one of the three sectors of the ITU. It coordinates standards for telecommunications by creating the ITU-T Recommendations.

What is "E.164"?

E.164 is an ITU-T Recommendation titled "The international public telecommunication numbering plan" that defines a numbering plan for the PSTN. This specifies how to write any telephone number for any country and telephony operator in the world. It limits telephone numbers to a maximum of 15 digits including international country code, area code, and local number, usually prefixing the number with a plus sign ("+") to indicate this format.

What is "PSTN" or "Public Switched Telephone Network"?

The Public Switched Telephone Network is the global network resulting of all the interconnections between all the national, regional, and local networks of all the telephony operators in the world, that makes it possible for any subscriber to reach any other subscriber in the world by making a telephone call. The PSTN protocols and equipments conform to the ITU-T recommendations.

What is "PLMN" or "Public Land Mobile Network"?

The Public Land Mobile Network is a network operated by an organization with the sole purpose of providing land mobile telecommunications services to the public.

Each operator desiring to provide such services has its own network, and each network is identified by its Moblie Country Code (or MCC) and its Mobile Network Code (or MNC).

PLMNs are accessed by air (wireless, involving radio communications) and need to be connected to the Public Switched Telephone Network (PSTN) in order to route calls. PLMNs are interconnected to the PSTN and to each other via wireless links and/or fiber optics.

What is "HLR" or "Home Location Register"?

The Home Location Register (HLR) is one of the main components of a GSM network. It's a database that contains all the numbers for all the subscribers that are allowed to use the network, and there can be many HLRs per PLMN (each one with many nodes in turn). One pair of IMSI/MSISDN is associated to one and only one HLR.

Every detail of every SIM card issued by the operator is stored in the HLRs, using the IMSI and the MSISDN as primary keys.

What is "MSISDN" or "Mobile Station International Subscriber Directory Number"?

The Mobile Station International Subscriber Directory Number (or MSISDN) is the telephone number to the SIM card in a mobile phone. The MSISDN complies with the ITU-T recommendation E.164.

A SIM has a unique IMSI that does not change, while the MSISDN can change in time.

What is "IMSI" or "International mobile subscriber identity"?

The International Mobile Subscriber Identity (or IMSI) is unique (worldwide) 64 bit number used to identify the user of a cellular network, and also used to query for service details from the HLR. This number is provisioned in the SIM card.

An IMSI is usually presented as a 15 digit number. The first 3 digits are the Mobile Country Code (MCC), followed by the Mobile Network Code (MNC), either 2 digits (European standard) or 3 digits (North American standard).

The length of the MNC depends on the value of the MCC. The remaining digits are the Mobile Subscription Identification Number (MSIN) within the network's customer base.

The IMSI conforms to the ITU E.212 numbering standard.

What are "MCC" ("Mobile Country Code") and "MNC" ("Mobile Network Code")?

Mobile Country Code (MCC) and Mobile Network Code are defined in the ITU-T E.212 Recommendation. The first digit of the MCC correspond to a specific region:

  • 0 - Test networks
  • 2 - Europe
  • 3 - North America and the Caribbean
  • 4 - Asia and the Middle East
  • 5 - Oceania
  • 6 - Africa
  • 7 - South and Central America
  • 9 - World-wide (Satellite, Air - aboard aircraft, Maritime - aboard ships, Antarctica)

The MCC is used with the MNC to uniquely identify an MNO (Mobile Network Operator), or carrier. Some network operators do not have their own radio access network at all. These are called mobile virtual network operators (MVNO).

The number resulting for combining the MCC, the MNC, and the MIN form the IMSI.

See also: Where can I get a list of all the mobile network operators?.

What is "MIN" or "Mobile Identification Number"?

The Mobile Identification Number (MIN) or Mobile Subscription Identification Number (MSIN) is a unique number of 10 digits long that a wireless carrier uses to identify a mobile phone. It's also the last part of the IMSI.

What is a "SIM card" or "Subscriber Identity Module"?

The Subscriber Identity Module is an integrated circuit that stores the IMSI and its related key, used to identify and authenticate subscribers on mobile telephony devices.

Where can I get a list of all the mobile network operators?

You can get the full list of globally known Mobile Network Operators (MNOs) from:

What is "NER" or "Network Effectiveness Ratio"?

Network Effectiveness Ratio (NER) is defined by the ITU. It measures and represents the network capability of terminating calls successfully (this includes calls terminated due to user actions, like busy signals and unanswered calls), in contrast to ASR (Answer-Seizure Ratio). See also Why was my campaign stopped due to "Low NER"?.

For more information, see the WikiPedia page entry for NER.

What is "ACD" or "Average Call Duration"?

"Average Call Duration" is the average time that calls are in the "answered" state.

We use this value in order to automatically tune the algorithm that spawns new calls in telephony campaigns, more specifically, we use the answer time for the Leg B of the calls when present, otherwise we use the value from Leg A.

See How do you calculate how many calls are needed in order to feed my agents?

What is "Post Call Work Duration"?

This is the time an agent needs to finish the administrative work after taking each call. It might go from a few seconds up to a minute, and usually includes filling some paperwork or information in a CRM.

See How do you calculate how many calls are needed in order to feed my agents?

What is "TCPA" or "Telephone Consumer Protection Act"?

The TCPA is a US law that restricts the use of automated telephone equipment, automatic dialing systems, artificial or prerecorded voice messages, SMS text messages, and fax machines. It protects consumers from receiving unsolicited messages and calls and enforces several guidelines that companies must follow before contacting their customers.

You must make sure that you comply with this law if your company contacts people in the US.

Below you will find some articles that are highly recommended to read. This should not be taken as legal advice and you should ask your attorney before sending messages to people in the US.

You can also read related information about marketing best practices in "Where can I read about Best Practices for SMS Marketing Campaigns and Notifications?".

What is "E-SIGN" or "Electronic Signatures in Global and National Commerce Act"?

The E-SIGN is a United States federal law that facilitates the use of electronic records and electronic signatures in interstate and foreign commerce by ensuring the validity and legal effect of contracts entered into electronically. This is important because it is related to the validity of the "Previous Written Consent" taken by online forms required by the TCPA.

You can read more at the Wikipedia entry for E-SIGN.


Pricing

How much does a single credit cost?

If you already have an account, you can see your current credit cost in your panel.

If you don't have an account yet or you need to get a better price based on your volume, please contact us, we'll be happy to help you!

How much does a DID cost?

DID costs vary depending on the country and the type (toll free, local, mobile, etc). All DIDs have both an NRC (Non Recurring Charge) and an MRC (Monthly Recurring Charge).

We can also adjust these according to your needs and volume desired. Please contact us and let us know your needs!

Can I get a volume discount?

You must certainly can! Please contact us and tell us what you're looking for exactly, our sales team will be glad to help you out.

What are your tariffs?

Our prices are in credits, and your price per credit might vary according to your volume. Nevertheless you can see your cost per credit and the tariffs in credits for different countries in your panel or through the Tariffs REST API.


Billing

How are my messages billed?

For each destination there is a tariff (See What are your tariffs?) and your message is divided into segments according to the number of characters and the encoding needed to send it:

  • If our system decides that your message can be sent by using the GSM_03.38 charset, then a segment can have at most 160 characters.
  • If your message can't be sent using the GSM_03.38 charset, then we need to use unicode with a segment of at most 70 characters.

Once the charset is determined, your message is divided into segments and we charge for each segment.

For example, let's say that the tariff for a given destination is 1 credit:

  • If your message can fit into a single GSM_03.38 charset segment (length of under 160 characters) you are charged 1 credit.
  • If your message needs (let's say) 2 GSM_03.38 segments, you are charged 2 credits.
  • If your message needs unicode and fits into a single unicode segment (length of under 70 characters), you are charged 1 credit.
  • If your meesage needs (let's say) 2 unicode segments, you are charged 2 credits.

You can also read more in our blog posts:

You can also test your messages, templates, and variables before sending a message to know in advance these details. See "Can I test how my message will look like and how much will it cost before sending it?".

NOTE: When your message has to be split into segments, there are a few bytes that need to be reserved to carry the concatenation information. This means that a GSM segment of a split message can have up to 153 characters, while a Unicode segment of a split message can have up to 67 characters. You should take this into account when estimating the total cost of your message.

Do I get charged if an SMS was not delivered?

Your account will be charged as soon as our systems apply the basic sanity checks and accept your request for delivery. At this stage, your message will be routed to one of our downstream carriers, and one of the following can happen:

  • If they reject your message immediately, your account will be refunded.
  • If our downstream carriers accept your message for delivery, you won't be refunded even if the message didn't reach the destination.

See also Do I get charged for "undelivered" messages?.

Can I send and receive SMS if I'm out of credits?

You won't be able to send any messages unless your account has enough credits. However, you will still be able to receive inbound SMS and they will be charged as usual, perhaps giving you a negative balance.

Can I have negative balance in my account?

Yes. See Can I send and receive SMS if I'm out of credits?.

Do I get charged for inbound messages?

Yes, you will be charged with 1 credit, no matter where it comes from. However, please contact us if you expect a high volume of inbound messages and need a special price.

I think I've been unfairly charged. What can I do?

We apologize if you feel that you've been charged when you shouldn't have. Please contact us describing what happened and we will apply a bonus in credits to your account as soon as possible.

How can I add funds to my account?

To add credits to your account you have to use a credit card. You can add credit cards in your panel or through the Credit Cards REST API.

Once you have one or more valid credit cards in your account, you can buy credits from your panel or through the Recharge REST API.

Can I add funds automatically to my account on low balance?

Yes, you can automatically buy credits by using your available credit cards as soon as your balance reaches a given threshold (for example, you can buy $150 of credits when your balance reaches less than 100 credits). You can setup this behavior from in panel or through the User Settings REST API.

Do I get charged for "undelivered" messages?

Yes. See Why do I have so many "undelivered" messages in my campaign?. Undelivered means that we tried to deliver your message, but one of our downstream carriers (or other carriers in the route) rejected the message because the number is invalid, it does not exist, or it's a fixed line.

Can I see a summary/report of the activity in my account?

Yes! There's a summary available in your panel showing (with a given date range) how many inbound and outbound messages where processed by country, and also how many credits you spent on them.

You can also access this information via the Summary REST API, and also from one of our Available SDKs.


Number Verification

Do you provide a way to authenticate mobile phone numbers?

Absolutely. You can verify mobile phone numbers by using our API or one of our Available SDKs.

You can also read more at our blog:


Number Inspect

Do you provide a way to filter/distinguish landline (or fixed) from mobile phone numbers?

Yes! This feature is available in our Number Inspect API directly, and through one of our Available SDKs, and also from your panel.

When using this feature you will be able to know if a given telephone number (in E164 format) belongs to a fixed/landline or a mobile subscriber. Along with this information you will also be able to get:

  • The country name and 2-letter iso code.
  • The MCC and MNC.
  • The name of the MNO.

You can use this feature to query for a single telephone number or upload a CSV with several ones. When uploading a CSV you will be creating a Job so you don't have to be online during the length of the operation (you will receive an email notifying of the results when it's done, so you can download a ZIP file with the report).

NOTE: This operation might have a cost (in credits), so be sure to check your panel first to know it beforehand.

For more information see our blog post "Landline or Mobile? Lower your SMS costs and avoid fraud".


CNAM Database Lookups

Can I access the CNAM database?

Yes, you can! We have a special API endpoint for this feature, and it's also available through our Available SDKs, and of course your user panel.

You can read more at our blog, in Improving Leads Quality with Caller ID Information.

You can use this feature to query for a single telephone number or upload a CSV with several ones. When uploading a CSV you will be creating a Job so you don't have to be online during the length of the operation (you will receive an email notifying of the results when it's done, so you can download a ZIP file with the report).

NOTE: This operation might have a cost (in credits), so be sure to check your panel first to know it beforehand.


PortaSMS

What is the PortaSMS service?

The PortaSMS service allows you to send and receive SMS messages with your current company landline number in the US. It can be used with local numbers, national numbers, and toll frees. This is a great way to add a new channel to communicate with your clients through one of the most important parts of your company identity: its phone number.

Read more in our blog post "Adding SMS capabilities to your current company number".

How can I acquire the PortaSMS service?

It's actually pretty straightforward. The first step is to create your PortaText account, so if you don't have one yet, head over to our website at https://www.portatext.com/signup and create one.

Once you have created your PortaText account, download the PortaSMS authorization form, complete it and send it back to us along with a digital copy of the telephone bill corresponding to the telephone number where you want to activate the service.

You can send all the information by either opening a ticket in our Support Center directly, or through your user panel by clicking "Help&Support". You can also send it via email to support@portatext.com.

Once approved, your number should be able to handle SMS traffic in the next 24 hours.


SMS

How can I make sure I will never send a message to a specific number?

Your account has a Blacklist where you can dynamically add and remove numbers. Any blacklisted numbers will never receive any messages. You can also read more about it in our blog post "Avoid SPAM Reports by Blacklisting your Contacts".

Also, make sure that you read and are familiar with the TCPA and E-SIGN laws if you are going to contact people in the US.

Is there a way for a target number to "opt-out" or "opt-in"?

There is no automatic way for a client to opt out or opt in of your messages when using a long code, but you can use your Blacklist to make sure you will never send any messages to a set of specific numbers. See How can I make sure I will never send a message to a specific number?.

NOTE: There is, however, the possibility of enabling the auto-detection of the word "STOP" in a specific DID through the DID Settings REST API and your panel, this will automatically send a contact to your blacklist if the word STOP is detected on an inbound message, and a confirmation message (charged as a regular message to your account) will be sent to the target.

For short codes and sms services there is a specific message flow to help you with this task automatically. See How do users opt in and opt out of my service?

Also, make sure that you read and are familiar with the TCPA and E-SIGN laws if you are going to contact people in the US.

Are there any constraints or limits for the SMS content/text?

Yes, there are some rules:

  • Inbound messages:
  • With less than 1 character will be silently discarded and will also wont be charged to you.
  • Outbound messages:
  • Must have at least 5 characters long to be accepted for delivery.

Also, if you will be using languages other than English for your messages, you should read How are my messages billed?.

Can I set a text to auto-reply to inbound messages?

Absolutely! You can set 1 text per DID to be automatically sent to your client on every inbound message. You can configure this in your panel or through the DID Settings REST API.

Can I send messages to the entire world?

Of course! You can see the current tariffs for different countries in your panel or through the Tariffs REST API. However you won't be able to send to a country if you don't see a tariff for it. If you don't see a country you're interested in, please contact us and let us know your needs, we'll get you a route for the country as soon as possible.

Will my clients be able to reply to every SMS?

It is possible that the source number appearing in the target mobile differ from the one you specified when sending the message (see Why do my clients receive the message from different Caller IDs?).

In these particular situations, your clients will be able to reply the SMS but you won't receive it. This should not happen when sending from a DID of a country to a target number in the same country.

If you think this is happening to you, please contact us and let us know.

Why do my clients receive the message from different Caller IDs?

We send our messages through different carriers and in turn they might send them through their own. So it is possible (and this is specially true when sending from a DID of a country to a destination in another country) that one of the carriers will change the source number by one of their own, and this is the number that will show up in the target mobile. See also Will my clients be able to reply to every SMS?.

If you think this is happening to you, please contact us and let us know.

How can I massively send a message with custom fields?

See this blog post. Remember that short codes are the only legal way to send marketing messages. See SMS Services and Short Codes

Can I get the Name or Caller ID information of the person sending me an SMS?

Yes you can. Please see Can I access the CNAM database?.

Why do I have so many "undelivered" messages in my campaign?

The error "undelivered" means that your message could not be routed to a mobile phone. This could be because the number is invalid, it doesn't exist, or it's actually a fixed line. See Do I get charged for "undelivered" messages?.

My campaign has finished but I still see some messages in status "sending". What about that?

In order to be sure that a message was sent, received, read, or rejected, we have to wait for one of our downstream carriers' notification (just as you wait for our delivery statuses when using Notifications. It may happen that some particular destinations take longer, perhaps a day or two before knowing for sure that the message was rejected or sent successfully, that's why you still see some message in the "sending" state.

Is there any way to avoid sending SMS to landline/fixed phone numbers?

Of course! See Do you provide a way to filter/distinguish landline (or fixed) from mobile phone numbers?

Can I send messages in languages other than English?

Yes you can! Our systems will try to automatically determine if your message fits into the GSM_03.38 charset and if not, it will use Unicode to send it. Note that unicode needs more bits to encode some characters, so there might be a chance that your messages are more expensive if your content is long.

For more information see How are my messages billed?.

You can also read more in our blog post "Unicode in your SMS: Emojis and Non-English Characters".

Can I test how my message will look like and how much will it cost before sending it?

Yes, you can use our Simulate API endpoint to test how your text (and/or template with variables) will look like when sending it, but you will also know the encoding needed, the number of segments (See "How are my messages billed?"), the maximum number of characters per segment, total cost, and many other things!

You can access this feature in your panel, through one of our Available SDKs, or just use our REST API by yourself.

Can I use SMS with my current company number or toll free?

Of course you can!. See What is the PortaSMS service?.


SMS Services and Short Codes

What is the difference between a long code and short code?

A long code (or DID, for Direct Inward Dial) is a telephone number that can be reached from anywhere in the world telephony network (or PSTN). A Short Code, on the other hand, is only available in the country where it is requested.

This means that by using a DID to send your messages, you can reach any mobile phone number in the world, while a short code will only be useful to reach only the mobile numbers that are in the same country as your short code. In order to "go global", you will need a short code from each country you are interested in (if you are lucky enough, you might find the same short code available in different countries!).

Long codes will not be able to sustain marketing campaigns or a high number of messages because carriers will block them. Short Codes, on the other hand, are dedicated to be used to run marketing campaigns or send notifications to a high number of users.

See also our post "Short Codes or Long Codes? Benefits and Drawbacks for your SMS Campaigns".

What is an SMS Service, and how it is related to a Short Code?

An SMS Service is composed of a short code (tied to a specific country, of course), and a keyword. The keyword is the name of your service and it is used by your clients to interact with it. You can access your sms services via the SMS Service API.

As an example, let's say that we have an SMS Service running on the short code 12345 for the US, and accessible via the keyword BESTDEALS.

What are the different SMS Services types and use cases?

SMS Services can currently be used for marketing or notification purposes.

How do I request an SMS Service?

Glad you asked! Just send us an email, and specify the following information so we can review your request and assign a short code for your sms service:

  • Country.
  • Keyword (this should be between 4 to 16 characters long).
  • Minimum age for the subscribers.
  • Single or Double Opt ins.
  • Intended use (marketing or notifications).
  • Examples for every kind of messages you will send.
  • Messaging frequency (How often will you be sending messages to your users).
  • Advertising examples (How will you be advertising your short code and sms service).

What are the legal requirements for an SMS Service?

Privacy and SPAM are taken seriously by carriers throughout the world, so countries and carriers in general might have different legal and technical requirements before assigning a short code or letting traffic pass through.

In the US, we comply with the CTIA recommendations and Best Practices. For more information, you can read the CTIA Short Code Monitoring Handbook.

To sum up, you MUST comply with the following:

  • Offer your users a clear "Terms And Conditions" URL.
  • Offer a telephone number so your users can reach out to you.
  • Offer a simple way to opt in and out of your service.
  • Offer periodic subscription reminders for your users.
  • NEVER send messages with adult content, or related to drug abuse, or any kind of criminal behavior.
  • NEVER send more messages than what your users subscribed to.
  • NEVER use a commercial transaction as a way to subscribe your clients to your service. Users should explicitly subscribe to your service with a prior written consent. A web page or an SMS subscription can also be used for this.
  • NEVER send messages to a mobile that is not subscribed to your service. Short Codes must only be used via a Permission Marketing philosophy.

We do take care of some of this automatically for you (like opt ins and opt outs), see How does the message flow of a SMS Service look like?.

PROHIBITED CONTENT: The CTIA also prohibits the following types of message content.

  • Adult content (e.g., pornography, nude dancing clubs, escort services)
  • Illegal or illicit drugs (e.g., marijuana)
  • Alcohol, tobacco, or firearms
  • Gambling
  • Violence, hatred, or profanity
  • Any product or service related to death (e.g., mortuaries and cemeteries)
  • Any mention of any wireless carrier or any representation that copies or parodies any product or service of any wireless carrier

You should also make sure that you understand and comply with the TCPA and E-SIGN laws in the US.

See also How should I promote my SMS Service?.

How should I promote my SMS Service?

FOR US SHORT CODES: You must include the disclosure shown below in ALL of your promotional materials including website, printed material, digital and event promotions, verbal announcements, broadcasts, and any other material or announcements promoting your mobile keyword. The TCPA and CTIA strictly prohibit omission of this disclosure in whole or in part. Failure to include the following terms may result in third-party legal action and suspension of your mobile keyword without warning.

Summary Terms & Conditions: Our mobile text messages are intended for subscribers over the age of ||MINIMUM AGE FOR YOUR SERVICE|| and are delivered via USA short code ||YOUR SHORT CODE||.You may receive up to ||MSG FREQUENCY|| message(s) per month for text alerts. Message and data rates may apply. This service is available for subscribers on AT&T, Verizon Wireless, T-Mobile®, MetroPCS, Sprint, Virgin Mobile USA, Cincinnati Bell, Centennial Wireless, U.S. Cellular®, Boost, and others in the US. Many international carriers are also supported. The list of international carriers include SaskTel, Microcell Connexions, NorthernTel Mobility, MTS Communication, Telebec, Aliant Mobility, Telus, Virgin Mobile Canada, Bell Mobility, and Rogers. The wireless carriers are not liable for delayed or undelivered messages. For help, text HELP ||YOUR KEYWORD|| to ||YOUR SHORT CODE||, email ops@portatext.com, or call +1(305)570-2828. You may stop your mobile subscription at any time by text messaging STOP ||YOUR KEYWORD|| to ||YOUR SHORT CODE||.

The number of messages per month should accurately reflect your intended messaging frequency. We recommend no more than four messages a month to avoid burdening subscribers.

What are "Single opt in" and "Double opt in"?

These are two different ways to setup your SMS Service to support automatic subscriptions for your users.

When using Single Opt ins, anyone can subscribe to your service by sending your keyword to your short code.

When using Double Opt ins, the users are required to send your keyword along with the word YES to subscribe to your service (and will get a HELP message with these instructions instead when sending just your keyword).

How do users opt in and opt out of my service?

Your service can be setup to support single or double opt ins. For single opt ins, it's enough for a user to send your keyword to your short code. See also What are "Single opt in" and "Double opt in"?.

When using double opt ins, anyone interested in subscribing to your service can send the word YES and your keyword to your short code. For example, if you have an SMS service running in the short code 12345 for the US, and accessed via the keyword DEALS, anyone with a US mobile number can send YES DEALS or DEALS YES to 12345 to subscribe.

To opt out, the procedure is the same, but instead of sending YES, they can send any of the following words:

  • STOP
  • CANCEL
  • QUIT
  • UNSUBSCRIBE
  • END
  • BAJA

For more information see How does the message flow of a SMS Service look like?.

How does the message flow of a SMS Service look like?

This is a brief description of the message flow that we provide with all sms services, it includes subscription reminders, automatic opt in and opt out, and also the help feature.

Subscription reminder

Every 30 days, we will automatically send a subscription reminder to all your subscribers that look like this:

YOUR_KEYWORD: Hello! This is a subscription reminder.
STOP YOUR_KEYWORD to cancel. HELP YOUR_KEYWORD for help.
Msg freq varies. Msg & Data rates may apply.

HELP

When a client sends HELP YOUR_KEYWORD, we will send back:

YOUR_KEYWORD: T&Cs: YOUR_TC_URL, Call us at: YOUR_PHONE_NUMBER.
Send STOP YOUR_KEYWORD to cancel.
Msg freq varies. Msg & Data rates may apply.

OPT INs

When a client subscribes to your service (by either a single or double opt in), we automatically subscribe the number to your service, and also reply back with:

YOUR_KEYWORD: Thank you! You will receive recurring SERVICE_TYPE messages.
Reply HELP YOUR_KEYWORD for help. STOP YOUR_KEYWORD to cancel.
Msg freq varies. Msg & Data rates may apply.

OPT OUTs

When a client sends any of the stop words ("STOP", "CANCEL", "QUIT", "UNSUBSCRIBE", "END", "BAJA"), we automatically unsubscribe the number from your service and send back:

YOUR_KEYWORD: You have opted out and will not receive any more messages. Thank you.

Generic Welcome

When none of the above applies, we send back:

YOUR_KEYWORD: Welcome! Reply YES YOUR_KEYWORD to subscribe and receive
recurring SERVICE_TYPE messages.
Reply HELP YOUR_KEYWORD for help. T&Cs: YOUR_TC_URL.
Msg freq varies. Msg & Data rates may apply.

Do I get charged for automatic messages like help, opt in, opt out, etc?

Yes. You will be charged for both inbound and outbound messages as usual.

How do I send messages from an SMS Service?

You can use the same methods as when sending from a long code, by using your panel or our REST API. You can send individual messages or start a campaign.

Can I send a message to any number from a short code?

No, you can only send messages to users who subscribed to your service by any of the outlined methods above. You will get an error if you try to send a message from a short code to a number that is not subscribed.

Why are some of my SMS Service subscribers temporarily not receiving messages or removed from the subscription list?

On a daily basis we receive notifications from different carriers that might refer to one or more of your SMS services subscribers. For all of those notifications we must take action and we will notify through Notifications. Here's a list of when and why you will get these notifications:

Status Reason Action Taken
Cancelled The mobile phone number is no longer active or changed owner We have to remove this number from you subscribers list.
Paused Temporarily no short code messages can be sent to this number The number will still be in your subscribers list but no messages will be sent to it until the subscription is resumed.
Resumed For a previously paused subscription, short code messages can now be sent again You will be able to send short code messages again to this number.
Changed A subscribed user changed his/her mobile phone number, the new number should be used from now on to send the short code messages The number will be automatically changed to the new number without any other further action needed.

MMS

Do you support MMS?

Not at the moment, although we are still considering it and will include support if there are enough compelling reasons. Our main reasons so far "against" it are:

  • MMS is not as effective as a simple SMS. MMS requires to be tested against a variety of devices in order to be sure that your clients will receive it successfully. SMS will work every single time and will not depend on the kind of device your clients have.
  • The same result of an MMS can be achieved with a simple SMS with a short link to the multimedia content.
  • MMS are significantly more expensive than SMS.
  • MMS are not widely available in the world. If you are contacting customers in other countries, it's almost certain that your message won't be delivered or at least won't be received with the content you intended.
  • Not all of our customers are interested in using it.

If you are interested in using MMS, please contact us so we can learn more about your use case.


Bulk SMS

Can I do bulk sending?

Yes, we offer SMS Campaigns. You can set them up in your panel or through the Campaigns REST API.

Also, make sure that you read and are familiar with the TCPA and E-SIGN laws if you are going to contact people in the US.

Do you support contact or distribution lists?

Yes. You can set them up in your panel or through the Contact List REST API. You can then send messages to one or more of these by setting up a Campaign. See also Can I do bulk sending?.

What happens if my account runs out of funds during a campaign?

No worries, your campaign will be automatically paused. You should manually restart your campaign from your panel or via the Campaign Lifecycle REST API.

Can I schedule my messages so specific times are honored for the targets?

Absolutely. This is great to respect your customers/users and is in line with good SMS Marketing karma.

You can use our Schedules to send your single messages or your campaign messages directly from your panel, from our REST API, or through one of our Available SDKs.

When you specify your schedule, all timing information (days, months, hours) will be applied to each specific destination in your messages (and it doesn't matter if you are sending a simple message or doing Group Messaging, or SMS Marketing Campaigns, or plain A2P for your company).

For more information see our blog post Schedule your SMS Marketing Campaigns for a better ROI.

Can I distribute my campaign messages across different DIDs?

Absolutely. Just select multiple DIDs as the "from" for your campaigns, you can use your panel or our Campaigns REST API.


Telephony

How do you determine that a given target has been contacted?

For any given call, we follow a few rules to determine if a given contact need to be contacted again or not. The following table describes the algorithm used.

Leg A Flow has AMD? AMD Result Empty flow for AMD result? Flow has forward? Leg B Result
X X
X X
X
X X X
HANGUP X
MACHINE / HUMAN / NOTSURE X
MACHINE / HUMAN / NOTSURE X X
MACHINE / HUMAN / NOTSURE X X X
MACHINE / HUMAN / NOTSURE X

NOTES

• = Not taken into account

X = Failed, Not present, or No.

✓ = Success, Present, or Yes.

"Flow Has Forward?" = Refers to the "current flow" being evaluated, and if this flow has a call flow object of type "Forward". I.e: When not inside an AMD flow, refers to the main flow, otherwise to one of these AMD subflows (if_human, if_machine, if_notsure).

A failed Result (X) means that the contact failed, so in the next iteration we will try to contact it again. A success Result (✓) means that the contact was successful, so we will not try to contact this target again.

Why was my campaign stopped due to "Low NER"?

If we detect that your campaign has a NER below 80%, we will automatically stop it. To calculate this we take into account all the issued calls for the campaign, and consider failed calls the ones that match any of the given criteria:

  • Leg A ended with result other than "ANSWER", "BUSY", "NO_ANSWER".
  • Leg B ended with result other than "ANSWER".

We then sum all the failed calls and if they are over the given threshold, we will consider that your campaign contacts or perhaps your SIP trunks don't have the required quality that we expect.

If this is affecting you, please check your SIP trunks, your campaign contacts, and if everything looks good please get in touch with us.

How do you calculate how many calls are needed in order to feed my agents?

We use a variation of the Erlang C formula, that auto adjusts itself according to the results of a running campaign, and takes into account the following parameters:

  • Agent occupancy: Defaults to 90%.
  • ACD or "Average Call Duration" (auto adjusted at runtime).
  • Post call work duration (set at campaign creation).
  • Number of agents (set at campaign creation, and also limited by your account limits).
  • Probability of call being answered (auto adjusted at runtime).

What codecs do you use for the calls?

We use G729 for both Leg A and Leg B of the calls, you should make sure that you support this codec in your SIP trunks. If you have difficulties in making this work, please contact us, we'll do our best to help you out.

What IP addresses should I allow in my firewalls?

You should allow the following IP addresses in your firewall for UDP ports 5060, and 10000-20000.

When Leg B is established (if any) the RTP traffic will flow directly between your SIP trunks, so we will not send any RTP traffic directly from then on.

  • 52.42.246.94

Alerts and Notifications

Can I receive an email on every inbound SMS?

Absolutely. You can setup this in your panel or through the User Settings REST API.

Can I receive email alerts when ...?

We send different email alerts on different events (some can be setup in your panel and through the User Settings REST API):

  • You open your account.
  • Your account has less than X credits.
  • Your account has 0 or less credits.
  • Your account profile has changed.
  • Your password was changed.
  • Your ACL has changed.
  • You receive a bonus.
  • A recharge has made to your account.
  • An auto-recharge failed for your account.
  • A new DID has been assigned to your account.
  • A DID has been removed from your account.
  • MRC or NRC have been charged to your account.
  • We failed to charge MRC or NRC to your account.
  • An SMS Service was approved for you.
  • A new subscriber has opted in for your SMS service.
  • A subscriber has opted out of your SMS service.
  • One of your credit cards will expire soon.
  • Your monthly has been successfully charged.
  • We failed to charge your monthly fee.
  • A job has finished.
  • A telephony campaign has been automatically stopped due to low NER.
  • SPAM reports in any of your DIDs.

Can you send notifications to my application?

Yes, you can setup Notifications in your panel.

What IP addresses should I allow in my firewall to receive HTTP notifications?

You should allow the following IP addresses for ports TCP 80 and/or 443 depending on the URL that you've setup for this.

  • 52.36.159.71

REST API

Where's your official API documentation?

Right here, in the wiki for the REST API.

Do you provide any official client implementations?

Of course we do! We :heart: open source, so we made our clients available here in our GitHub repo at https://github.com/portatext. There's also a small wiki about our Available SDKs.

I've found a bug in the documentation and/or the official clients. What should I do?

That's great, we're always looking to improve our service. Please contact us or open an issue (or even better, a pull request) in the corresponding repository(ies) of the project(s). We'll be happy to review and fix it right away.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.