~~NOTOC~~

//[[restapi:start|RESTful API]]//

====== Phone List Guidelines ======

Generally when sending blasts you will need to create a recipient list. This recipient list its a file that contains the detailed information for each delivery. This file could also contain parameters for each particular case, this parameters help to customise each delivery by adding personalized information.

We have different file format depending on each case.

===== Basic CSV Recipient List =====

<WRAP group>

<WRAP half column>

\\ 

This file must be a text file and it which has one single column with the recipient mobile number.

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number

</WRAP>

</WRAP>

</WRAP>

==== Text File - Sample ====

<code>
13056708084
18133210984
</code>

===== Recipient List With Parameters =====

<WRAP group>

<WRAP half column>

\\ 
All parameters on the file are **optional**, the only **mandatory** parameter it's the recipient and it has to be at the first column

This file could be either a text file or an excel one.

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
13056708084;jane;doe
18133210984;john;doe
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (;)** to separate fields inside the text file. \\ \\ Parameters mechanism: \\ You may include //placeholders// in your message's content using **{#}** notation //(# its a real number starting in 0)//, if you include them, they will be replaced for the respective column's content starting from the 2nd column in this case.
</WRAP>

==== Excel File - Sample ====

Note that you don't have to use semicolon as separator when using excel files.

<WRAP half>
^  A  ^  B  ^  C  ^
| @white:13056708084 | @white:jane | @white:doe | 
| @white:18133210984 | @white:john | @white:doe |
</WRAP>

\\ 
===== SMSs Recipient List =====

<WRAP group>

<WRAP half column>

\\ 
The first 6 columns of this file are **mandatory**. Starting on the 7th column will be **optional** and must be related with the content of your message.

This file could be either a text file or an excel one.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Recipient's Mobile Number
  - From
  - Carrier Name
  - Text
  - Encoding  //Default UTF-8//
  - Timezone
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
13056708084;19893653744;CarrierName;UTF-8;America/New_York;Hi {0}. Welcome to {1};Matt Ford;this test
18133210984;19893653744;CarrierName;UTF-8;America/New_York;Hi {0}. Welcome to {1};Ed Harris;this test
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (;)** to separate fields inside the text file. \\ \\ Parameters mechanism: \\ You may include //placeholders// in your message's content using **{#}** notation //(# its a real number starting in 0)//, if you include them, they will be replaced for the respective column's content starting from the 7th column in this case.
</WRAP>
==== Excel File - Sample ====

Note that you don't have to use semicolon as separator when using excel files.

^  A  ^  B  ^  C  ^  D  ^  E  ^  F  ^  G  ^  H  ^
| @white:13056708084 | @white:19893653744 | @white:CarrierName | @white:UTF-8 | @white:America/New_York | @white:Hi {0}. Welcome to {1} | @white:Matt Ford | @white:this test |
| @white:18133210984 | @white:19893653744 | @white:CarrierName | @white:UTF-8 | @white:America/New_York | @white:Hi {0}. Welcome to {1} | @white:Ed Harris | @white:this test |

\\ 
===== SMSs Recipient List (simple) =====

<WRAP group>

<WRAP half column>

\\ 
Two single columns that define the recipient and the text message to send.

This file could be either a text file or an excel one.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Recipient's Mobile Number
  - Text

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
13056708084;Text message for user 13056708084
18133210984;Text message for user 18133210984
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (;)** to separate fields inside the text file. 
</WRAP>

\\
==== Excel File - Sample ====

Note that you don't have to use semicolon as separator when using excel files.

^  A  ^  B  ^
| @white:13056708084 | @white:Text message for user 13056708084 | 
| @white:18133210984 | @white:Text message for user 18133210984 |

\\

===== SMSs Recipient JSON =====

<WRAP group>

<WRAP half column>

\\ 
Similar to the SMSs recipient files this will include the mobilenumber and the text for each recipient
</WRAP>

<WRAP half column>

<WRAP round info>Expected tags, //if not listed it doesn't exist//: 

  - mobilenumber: Recipient's Mobile Number
  - text: The text to be sent to the recipient

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
[
{"mobilenumber":"00000000","text":"Test1 createBroadcastFromJson"},
{"mobilenumber":"00000001","text":"Test2 createBroadcastFromJson"}
]
</code>

\\

===== Email Recipient List =====

<WRAP group>

<WRAP half column>

\\ 
The first column of this file is **mandatory**. Starting on the 2nd column will be **optional** and must be related with the content of your message.

This file could be either a text file or an excel one.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Recipient's email address
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
matt_ford@ogangi.com;Matt Ford;April
ed_harris@ogangi.com;Ed Harris;March
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (;)** to separate fields inside the text file. \\ \\ Parameters mechanism: \\ You may include //placeholders// in your message's content using **{#}** notation //(# its a real number starting in 0)//, if you include them, they will be replaced for the respective column's content starting from the 7th column in this case.
</WRAP>
==== Excel File - Sample ====

Note that you don't have to use semicolon as separator when using excel files.

^  A  ^  B  ^  C  ^
| @white:matt_ford@ogangi.com | @white:Matt Ford | @white:April |
| @white:ed_harris@ogangi.com | @white:Ed Harris | @white:March |

\\
===== Recipient List (with variables) =====

<WRAP group>

<WRAP half column>

\\ 
The first column of this file is **mandatory**. Starting on the 2nd column will be **optional** and must be related with the content of your message.

This file could be either a text file or an excel one.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile number
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
13056708084;Matt Ford;April
18133210984;Ed Harris;March
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (;)** to separate fields inside the text file. \\ \\ Parameters mechanism: \\ You may include //placeholders// in your message's content using **{#}** notation //(# its a real number starting in 0)//, if you include them, they will be replaced for the respective column's content starting from the 7th column in this case.
</WRAP>
==== Excel File - Sample ====

Note that you don't have to use semicolon as separator when using excel files.

^  A  ^  B  ^  C  ^
| 13056708084 | @white:Matt Ford | @white:April |
| 18133210984 | @white:Ed Harris | @white:March |

===== Segmented Recipient List =====

<WRAP group>

<WRAP half column>

\\ 
All parameters on the file are **optional**, the only **mandatory** parameter is the recipient and it has to be at the first column

This file Must contain header and could be a csv file or excel.

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== Csv File - Sample ====

<code>
customer_phone_num,name,city
13056708084,jane,New York
18133210984,john,New York
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (,)** to separate fields inside the csv file.  Please read the [[:file_structure|File structure]] to learn more about this.
</WRAP>

==== Excel File - Sample ====

Note that you don't have to use semicolon as separator when using excel files.

<WRAP half>
^  A  ^  B  ^  C  ^
| @white:customer_phone_num | @white:name | @white:city | 
| @white:13056708084 | @white:jane | @white:New York | 
| @white:18133210984 | @white:john | @white:New York |
</WRAP>

\\
===== Black List (Add Users)=====

<WRAP group>

<WRAP half column>

\\ 
Three single columns that define each user.

This file must be a text file.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number
  - Black List Type
  - Comment

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
123456781;1;comment 1
123456782;2;other comment
123456783;3;more comment
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (;)** to separate fields and we use a new line for each user inside the text file. 
</WRAP>

\\
===== Black List (Delete Users)=====

<WRAP group>

<WRAP half column>

\\ 
One column that define each user.

This file must be a text file.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
123456781
123456782
123456783
</code>

<WRAP round tip>
Please be aware that we use a new line for each mobile number inside the text file. 
</WRAP>

\\
===== OWNCODE Recipient List =====

<WRAP group>

<WRAP half column>

\\ 
Two single columns that define the recipient and the text message to send.

This file could be either a text file or an excel one.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Recipient's Mobile Number
  - Text to send

</WRAP>

</WRAP>

</WRAP>
==== Text File - Sample ====

<code>
13056708084;Text message for user 13056708084
18133210984;Text message for user 18133210984
</code>

<WRAP round tip>
Please be aware that we use **//semicolon// (;)** to separate fields inside the text file. 
</WRAP>

\\
==== Excel File - Sample ====

Note that you don't have to use semicolon as separator when using excel files.

^  A  ^  B  ^
| @white:13056708084 | @white:Text message for user 13056708084 | 
| @white:18133210984 | @white:Text message for user 18133210984 |