> ## Documentation Index
> Fetch the complete documentation index at: https://yardim.whattalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Serbest Form Mesaj Gönder

> Aktif bir 24 saatlik oturum içinde serbest metin WhatsApp mesajı gönderin

Bu endpoint, bir alıcıya serbest form (serbest metin) WhatsApp mesajı gönderir. Şablon mesajlarından farklı olarak, serbest form mesajlar herhangi bir metin içerebilir ancak **aktif bir 24 saatlik mesajlaşma penceresi gerektirir** -- yani alıcının son 24 saat içinde WhatsApp gönderenize bir mesaj göndermiş olması gerekir.

<Warning>
  Serbest form mesajlar yalnızca aktif bir 24 saatlik mesajlaşma penceresi süresince gönderilebilir. Oturum süresi dolduysa, konuşmayı yeniden başlatmak için önce bir [şablon mesajı](/api-reference/whatsapp/send-template) göndermeniz gerekir. Oturumun aktif olup olmadığını kontrol etmek için [Oturum Durumu](/api-reference/whatsapp/session-status) endpoint'ini kullanın.
</Warning>

<Note>
  Bu endpoint, kullanıcı başına **saniyede 5 istek** ile hız sınırlıdır.
</Note>

### İstek Gövdesi

<ParamField body="sender_id" type="integer" required>
  Mesajın gönderileceği WhatsApp göndereninin kimliği ([Gönderenleri Getir](/api-reference/whatsapp/get-senders) endpoint'inden elde edilir)
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  Alıcının uluslararası formattaki telefon numarası (ör. `+1234567890`)
</ParamField>

<ParamField body="message" type="string" required>
  Gönderilecek mesaj içeriği (maksimum 4096 karakter)
</ParamField>

### Yanıt Alanları

<ResponseField name="success" type="boolean">
  Mesajın başarıyla gönderilip gönderilmediği
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  Bu mesajla ilişkili konuşma kimliği
</ResponseField>

<ResponseField name="message_id" type="integer">
  Konuşma mesajı kaydının kimliği
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  WhatsApp mesaj kaydının kimliği
</ResponseField>

<ResponseField name="message_sid" type="string">
  Teslimat takibi için Twilio mesaj SID'i
</ResponseField>

<ResponseField name="session_status" type="object">
  Mesaj gönderildikten sonra güncellenen oturum durumu

  <Expandable title="Oturum durumu özellikleri">
    <ResponseField name="is_open" type="boolean">
      24 saatlik mesajlaşma penceresinin şu anda açık olup olmadığı
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Şu anda serbest form mesajlar gönderilip gönderilemeyeceği
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Şablon mesajı gerekip gerekmediği
    </ResponseField>

    <ResponseField name="message" type="string">
      Oturum durumunun okunabilir açıklaması
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      24 saatlik pencerede kalan dakika sayısı
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      Oturumun sona ereceği ISO 8601 zaman damgası
    </ResponseField>
  </Expandable>
</ResponseField>

### Hata Yanıtları

<ResponseField name="402 Insufficient Balance">
  <Expandable title="Hata Yanıtı">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Insufficient balance. Please top up your account.`</ResponseField>
    <ResponseField name="error_code" type="string">`INSUFFICIENT_BALANCE`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="403 Session Expired">
  <Expandable title="Hata Yanıtı">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">24 saatlik mesajlaşma penceresinin süresinin dolduğunu belirten mesaj</ResponseField>
    <ResponseField name="error_code" type="string">`SESSION_EXPIRED`</ResponseField>

    <ResponseField name="session_status" type="object">
      `is_open`, `can_send_freeform`, `requires_template` ve `message` alanlarıyla mevcut oturum durumu
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found">
  <Expandable title="Hata Yanıtı">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found or does not belong to you`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="503 Sender Offline">
  <Expandable title="Hata Yanıtı">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Gönderenin şu anda çevrimdışı olduğunu belirten mesaj</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_OFFLINE`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.whattalk.ai/api/user/whatsapp/send-freeform" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+1234567890",
      "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.whattalk.ai/api/user/whatsapp/send-freeform',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        recipient_phone: '+1234567890',
        message: 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.whattalk.ai/api/user/whatsapp/send-freeform',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+1234567890',
          'message': 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Başarılı theme={null}
  {
    "success": true,
    "conversation_id": 1234,
    "message_id": 567,
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "session_status": {
      "is_open": true,
      "can_send_freeform": true,
      "requires_template": false,
      "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
      "minutes_remaining": 1425,
      "expires_at": "2026-02-25T10:30:00+00:00"
    }
  }
  ```

  ```json 402 Yetersiz Bakiye theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 403 Oturum Süresi Doldu theme={null}
  {
    "success": false,
    "error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
    "error_code": "SESSION_EXPIRED",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Session expired. Send a template or wait for customer to reply.",
      "expired_at": "2026-02-23T10:30:00+00:00"
    }
  }
  ```

  ```json 404 Gönderen Bulunamadı theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 422 Geçersiz Telefon theme={null}
  {
    "success": false,
    "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 503 Gönderen Çevrimdışı theme={null}
  {
    "success": false,
    "error": "Sender is not online. Current status: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### 24 Saatlik Mesajlaşma Penceresi

WhatsApp **24 saatlik mesajlaşma penceresi** politikası uygular:

1. Bir müşteri WhatsApp Business numaranıza mesaj gönderdiğinde, 24 saatlik bir pencere açılır.
2. Bu pencere süresince kısıtlama olmaksızın serbest form mesajlar gönderebilirsiniz.
3. Pencere süresi dolduktan sonra, konuşmayı yeniden başlatmak için [şablon mesajı](/api-reference/whatsapp/send-template) kullanmanız gerekir.
4. Her yeni müşteri mesajı 24 saatlik zamanlayıcıyı sıfırlar.

Serbest form mesaj göndermeye çalışmadan önce oturumun aktif olup olmadığını kontrol etmek için [Oturum Durumu](/api-reference/whatsapp/session-status) endpoint'ini kullanın.

### Notlar

* Maksimum mesaj uzunluğu **4.096 karakter**dir (WhatsApp limiti).
* Gönderen `online` olmalıdır. Çevrimdışı gönderenler `503` hatası döndürür.
* Mesaj maliyetleri otomatik olarak hesap bakiyenizden düşülür.
* Hız limiti: Kullanıcı başına saniyede 5 istek.